/ Hex Artifact Content
Login

Artifact 8e1ccddb12b5e983d0a17e1f1477c72b0a72dd84:


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 57 2e 58  of the form "W.X
0ba0: 2e 59 22 20 6f 72 20 22 57 2e 58 2e 59 2e 5a 22  .Y" or "W.X.Y.Z"
0bb0: 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61 6c 75 65  ..** The W value
0bc0: 20 69 73 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f   is major versio
0bd0: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 69 73 20  n number and is 
0be0: 61 6c 77 61 79 73 20 33 20 69 6e 20 53 51 4c 69  always 3 in SQLi
0bf0: 74 65 33 2e 0a 2a 2a 20 54 68 65 20 57 20 76 61  te3..** The W va
0c00: 6c 75 65 20 6f 6e 6c 79 20 63 68 61 6e 67 65 73  lue only changes
0c10: 20 77 68 65 6e 20 62 61 63 6b 77 61 72 64 73 20   when backwards 
0c20: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 73  compatibility is
0c30: 0a 2a 2a 20 62 72 6f 6b 65 6e 20 61 6e 64 20 77  .** broken and w
0c40: 65 20 69 6e 74 65 6e 64 20 74 6f 20 6e 65 76 65  e intend to neve
0c50: 72 20 62 72 65 61 6b 20 62 61 63 6b 77 61 72 64  r break backward
0c60: 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
0c70: 0a 2a 2a 20 54 68 65 20 58 20 76 61 6c 75 65 20  .** The X value 
0c80: 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72  is the minor ver
0c90: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20  sion number and 
0ca0: 6f 6e 6c 79 20 63 68 61 6e 67 65 73 20 77 68 65  only changes whe
0cb0: 6e 0a 2a 2a 20 74 68 65 72 65 20 61 72 65 20 6d  n.** there are m
0cc0: 61 6a 6f 72 20 66 65 61 74 75 72 65 20 65 6e 68  ajor feature enh
0cd0: 61 6e 63 65 6d 65 6e 74 73 20 74 68 61 74 20 61  ancements that a
0ce0: 72 65 20 66 6f 72 77 61 72 64 73 20 63 6f 6d 70  re forwards comp
0cf0: 61 74 69 62 6c 65 0a 2a 2a 20 62 75 74 20 6e 6f  atible.** but no
0d00: 74 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  t backwards comp
0d10: 61 74 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 59  atible..** The Y
0d20: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 72 65   value is the re
0d30: 6c 65 61 73 65 20 6e 75 6d 62 65 72 20 61 6e 64  lease number and
0d40: 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 65 64 20   is incremented 
0d50: 77 69 74 68 0a 2a 2a 20 65 61 63 68 20 72 65 6c  with.** each rel
0d60: 65 61 73 65 20 62 75 74 20 72 65 73 65 74 73 20  ease but resets 
0d70: 62 61 63 6b 20 74 6f 20 30 20 77 68 65 6e 65 76  back to 0 whenev
0d80: 65 72 20 58 20 69 73 20 69 6e 63 72 65 6d 65 6e  er X is incremen
0d90: 74 65 64 2e 0a 2a 2a 20 54 68 65 20 5a 20 76 61  ted..** The Z va
0da0: 6c 75 65 20 6f 6e 6c 79 20 61 70 70 65 61 72 73  lue only appears
0db0: 20 6f 6e 20 62 72 61 6e 63 68 20 72 65 6c 65 61   on branch relea
0dc0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ses..**.** The S
0dd0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0de0: 4d 42 45 52 20 69 73 20 61 6e 20 69 6e 74 65 67  MBER is an integ
0df0: 65 72 20 74 68 61 74 20 69 73 20 63 6f 6d 70 75  er that is compu
0e00: 74 65 64 20 61 73 0a 2a 2a 20 66 6f 6c 6c 6f 77  ted as.** follow
0e10: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
0e20: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 53 51  uote><pre>.** SQ
0e30: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
0e40: 42 45 52 20 3d 20 57 2a 31 30 30 30 30 30 30 20  BER = W*1000000 
0e50: 2b 20 58 2a 31 30 30 30 20 2b 20 59 0a 2a 2a 20  + X*1000 + Y.** 
0e60: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
0e70: 74 65 3e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20  te>.**.** Since 
0e80: 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20  version 3.6.18, 
0e90: 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
0ea0: 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72  de has been stor
0eb0: 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20  ed in the.** <a 
0ec0: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77  href="http://www
0ed0: 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f  .fossil-scm.org/
0ee0: 22 3e 66 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75  ">fossil configu
0ef0: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
0f00: 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e  t.** system</a>.
0f10: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55    The SQLITE_SOU
0f20: 52 43 45 5f 49 44 0a 2a 2a 20 6d 61 63 72 6f 20  RCE_ID.** macro 
0f30: 69 73 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  is a string whic
0f40: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0f50: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0f60: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0f70: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0f80: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0f90: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ent system.  The
0fa0: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73   string contains
0fb0: 20 74 68 65 0a 2a 2a 20 64 61 74 65 20 61 6e 64   the.** date and
0fc0: 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65   time of the che
0fd0: 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20  ck-in (UTC) and 
0fe0: 61 6e 20 53 48 41 31 20 68 61 73 68 20 6f 66 20  an SHA1 hash of 
0ff0: 74 68 65 20 65 6e 74 69 72 65 0a 2a 2a 20 73 6f  the entire.** so
1000: 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a  urce tree..**.**
1010: 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1020: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1030: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ],.** [sqlite3_l
1040: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1050: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f  ()], [sqlite3_so
1060: 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73  urceid()],.** [s
1070: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d  qlite_version()]
1080: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75   and [sqlite_sou
1090: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rce_id()]..**.**
10a0: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
10b0: 48 31 30 30 31 31 5d 20 5b 48 31 30 30 31 34 5d  H10011] [H10014]
10c0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
10d0: 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20  TE_VERSION      
10e0: 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65    "--VERS--".#de
10f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53  fine SQLITE_VERS
1100: 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52  ION_NUMBER --VER
1110: 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64  SION-NUMBER--.#d
1120: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55  efine SQLITE_SOU
1130: 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53  RCE_ID      "--S
1140: 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a  OURCE-ID--"../*.
1150: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1160: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
1170: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 20 7b 48  rsion Numbers {H
1180: 31 30 30 32 30 7d 20 3c 53 36 30 31 30 30 3e 0a  10020} <S60100>.
1190: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
11a0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 0a 2a 2a 0a  ite3_version.**.
11b0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
11c0: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
11d0: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
11e0: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
11f0: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
1200: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1210: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
1220: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 23 64 65  E_SOURCE_ID] #de
1230: 66 69 6e 65 73 20 69 6e 20 74 68 65 20 68 65 61  fines in the hea
1240: 64 65 72 2c 0a 2a 2a 20 62 75 74 20 61 72 65 20  der,.** but are 
1250: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
1260: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1270: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1280: 72 20 66 69 6c 65 2e 20 20 43 61 75 74 69 6f 75  r file.  Cautiou
1290: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
12a0: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
12b0: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
12c0: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
12d0: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
12e0: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
12f0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1300: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
1310: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
1320: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
1330: 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65   and thus insure
1340: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
1350: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
1360: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
1370: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
1380: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
1390: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
13a0: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
13b0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
13c0: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
13d0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
13e0: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
1410: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
1420: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1430: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
1440: 76 65 72 73 69 6f 6e 2c 53 51 4c 49 54 45 5f 56  version,SQLITE_V
1450: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1460: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1470: 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ote>.**.** The s
1480: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1490: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14a0: 75 72 6e 73 20 74 68 65 20 73 61 6d 65 20 69 6e  urns the same in
14b0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 0a  formation as is.
14c0: 2a 2a 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ** in the sqlite
14d0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
14e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
14f0: 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  e function is pr
1500: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 75 73  ovided.** for us
1510: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20  e in DLLs since 
1520: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c  DLL users usuall
1530: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 64 69  y do not have di
1540: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
1550: 74 72 69 6e 67 0a 2a 2a 20 63 6f 6e 73 74 61 6e  tring.** constan
1560: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c  ts within the DL
1570: 4c 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 74  L.  Similarly, t
1580: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1590: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 0a 2a  eid() function.*
15a0: 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 61  * returns the sa
15b0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
15c0: 73 20 69 73 20 69 6e 20 74 68 65 20 5b 53 51 4c  s is in the [SQL
15d0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 23  ITE_SOURCE_ID] #
15e0: 64 65 66 69 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  define of.** the
15f0: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2a   header file..**
1600: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
1610: 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d  qlite_version()]
1620: 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75   and [sqlite_sou
1630: 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a  rce_id()]..**.**
1640: 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
1650: 48 31 30 30 32 31 5d 20 5b 48 31 30 30 32 32 5d  H10021] [H10022]
1660: 20 5b 48 31 30 30 32 33 5d 0a 2a 2f 0a 53 51 4c   [H10023].*/.SQL
1670: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
1680: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1690: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
16a0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
16b0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
16c0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
16d0: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
16e0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
16f0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1700: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1710: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
1720: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
1730: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
1740: 65 20 7b 48 31 30 31 30 30 7d 20 3c 53 36 30 31  e {H10100} <S601
1750: 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  00>.**.** SQLite
1760: 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64   can be compiled
1770: 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74   with or without
1780: 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a   mutexes.  When.
1790: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
17a0: 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 65  HREADSAFE] C pre
17b0: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
17c0: 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78  is 1 or 2, mutex
17d0: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
17e0: 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20  d and SQLite is 
17f0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65  threadsafe.  Whe
1800: 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  n the.** [SQLITE
1810: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
1820: 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65  ro is 0, .** the
1830: 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69   mutexes are omi
1840: 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74  tted.  Without t
1850: 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69  he mutexes, it i
1860: 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f  s not safe.** to
1870: 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63   use SQLite conc
1880: 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f  urrently from mo
1890: 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65  re than one thre
18a0: 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69  ad..**.** Enabli
18b0: 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72  ng mutexes incur
18c0: 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70  s a measurable p
18d0: 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c  erformance penal
18e0: 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65  ty..** So if spe
18f0: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20  ed is of utmost 
1900: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d  importance, it m
1910: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69  akes sense to di
1920: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74  sable.** the mut
1930: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d  exes.  But for m
1940: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d  aximum safety, m
1950: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65  utexes should be
1960: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 54 68 65   enabled..** The
1970: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
1980: 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73  r is for mutexes
1990: 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a   to be enabled..
19a0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
19b0: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
19c0: 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69   by an applicati
19d0: 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  on to make sure 
19e0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73  that the.** vers
19f0: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68  ion of SQLite th
1a00: 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67  at it is linking
1a10: 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d   against was com
1a20: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
1a30: 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e  e desired settin
1a40: 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  g of the [SQLITE
1a50: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
1a60: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ro..**.** This i
1a70: 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65  nterface only re
1a80: 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d  ports on the com
1a90: 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20  pile-time mutex 
1aa0: 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68  setting.** of th
1ab0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1ac0: 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20  SAFE] flag.  If 
1ad0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
1ae0: 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54  ed with.** SQLIT
1af0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 74  E_THREADSAFE=1 t
1b00: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
1b10: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
1b20: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
1b30: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
1b40: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
1b50: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
1b60: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
1b70: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
1b80: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
1b90: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
1ba0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
1bb0: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
1bc0: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
1bd0: 47 5f 4d 55 54 45 58 5d 2e 20 20 54 68 65 20 72  G_MUTEX].  The r
1be0: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1bf0: 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  his function sho
1c00: 77 73 0a 2a 2a 20 6f 6e 6c 79 20 74 68 65 20 64  ws.** only the d
1c10: 65 66 61 75 6c 74 20 63 6f 6d 70 69 6c 65 2d 74  efault compile-t
1c20: 69 6d 65 20 73 65 74 74 69 6e 67 2c 20 6e 6f 74  ime setting, not
1c30: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
1c40: 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 74 68 61 74  anges.** to that
1c50: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
1c60: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
1c70: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
1c80: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
1c90: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1ca0: 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  n..**.** Require
1cb0: 6d 65 6e 74 73 3a 20 5b 48 31 30 31 30 31 5d 20  ments: [H10101] 
1cc0: 5b 48 31 30 31 30 32 5d 0a 2a 2f 0a 69 6e 74 20  [H10102].*/.int 
1cd0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
1ce0: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
1cf0: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
1d00: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
1d10: 61 6e 64 6c 65 20 7b 48 31 32 30 30 30 7d 20 3c  andle {H12000} <
1d20: 53 34 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S40200>.** KEYWO
1d30: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
1d40: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
1d50: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1d60: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
1d70: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1d80: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
1d90: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
1da0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
1db0: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
1dc0: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
1dd0: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
1de0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
1df0: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
1e00: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
1e10: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
1e20: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1e30: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1e40: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1e50: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
1e60: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
1e70: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
1e80: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
1e90: 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65  ()].** is its de
1ea0: 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65  structor.  There
1eb0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20   are many other 
1ec0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
1ed0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
1ee0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
1ef0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
1f00: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
1f10: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
1f20: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
1f30: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
1f40: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
1f50: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
1f60: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
1f70: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1f80: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
1f90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
1fa0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
1fb0: 73 20 7b 48 31 30 32 30 30 7d 20 3c 53 31 30 31  s {H10200} <S101
1fc0: 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  10>.** KEYWORDS:
1fd0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
1fe0: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
1ff0: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2000: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2010: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2020: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2030: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2040: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2050: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
2060: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
2070: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
2080: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2090: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
20a0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
20b0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
20c0: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
20d0: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
20e0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
20f0: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2100: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2110: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2120: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2130: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
2140: 5b 48 31 30 32 30 31 5d 20 5b 48 31 30 32 30 32  [H10201] [H10202
2150: 5d 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ].*/.#ifdef SQLI
2160: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20  TE_INT64_TYPE.  
2170: 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49  typedef SQLITE_I
2180: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2190: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
21a0: 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54  f unsigned SQLIT
21b0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
21c0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69  ite_uint64;.#eli
21d0: 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56  f defined(_MSC_V
21e0: 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f  ER) || defined(_
21f0: 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74  _BORLANDC__).  t
2200: 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73  ypedef __int64 s
2210: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2220: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2230: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  __int64 sqlite_u
2240: 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74  int64;.#else.  t
2250: 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67  ypedef long long
2260: 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36   int sqlite_int6
2270: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2280: 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20  igned long long 
2290: 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  int sqlite_uint6
22a0: 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65  4;.#endif.typede
22b0: 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  f sqlite_int64 s
22c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79  qlite3_int64;.ty
22d0: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e  pedef sqlite_uin
22e0: 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  t64 sqlite3_uint
22f0: 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f  64;../*.** If co
2300: 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72  mpiling for a pr
2310: 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63  ocessor that lac
2320: 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  ks floating poin
2330: 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75  t support,.** su
2340: 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72  bstitute integer
2350: 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f   for floating-po
2360: 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  int..*/.#ifdef S
2370: 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54  QLITE_OMIT_FLOAT
2380: 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69  ING_POINT.# defi
2390: 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  ne double sqlite
23a0: 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a  3_int64.#endif..
23b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23c0: 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61  Closing A Databa
23d0: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48  se Connection {H
23e0: 31 32 30 31 30 7d 20 3c 53 33 30 31 30 30 3e 3c  12010} <S30100><
23f0: 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S40200>.**.** Th
2400: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68  is routine is th
2410: 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  e destructor for
2420: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2430: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  bject..**.** App
2440: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2450: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2460: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
2470: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
2480: 74 65 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20  tements].** and 
2490: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
24a0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
24b0: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20   [BLOB handles] 
24c0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a  associated with.
24d0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ** the [sqlite3]
24e0: 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f   object prior to
24f0: 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63   attempting to c
2500: 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e  lose the object.
2510: 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
2520: 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 20 69 6e  _next_stmt()] in
2530: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
2540: 73 65 64 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  sed to locate al
2550: 6c 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  l.** [prepared s
2560: 74 61 74 65 6d 65 6e 74 73 5d 20 61 73 73 6f 63  tatements] assoc
2570: 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
2580: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2590: 6e 5d 20 69 66 20 64 65 73 69 72 65 64 2e 0a 2a  n] if desired..*
25a0: 2a 20 54 79 70 69 63 61 6c 20 63 6f 64 65 20 6d  * Typical code m
25b0: 69 67 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74  ight look like t
25c0: 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
25d0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
25e0: 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
25f0: 74 6d 74 3b 0a 2a 2a 20 77 68 69 6c 65 28 20 28  tmt;.** while( (
2600: 70 53 74 6d 74 20 3d 20 73 71 6c 69 74 65 33 5f  pStmt = sqlite3_
2610: 6e 65 78 74 5f 73 74 6d 74 28 64 62 2c 20 30 29  next_stmt(db, 0)
2620: 29 21 3d 30 20 29 7b 0a 2a 2a 20 26 6e 62 73 70  )!=0 ){.** &nbsp
2630: 3b 20 20 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ;   sqlite3_fina
2640: 6c 69 7a 65 28 70 53 74 6d 74 29 3b 0a 2a 2a 20  lize(pStmt);.** 
2650: 7d 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  }.** </pre></blo
2660: 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 49  ckquote>.**.** I
2670: 66 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  f [sqlite3_close
2680: 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ()] is invoked w
2690: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
26a0: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
26b0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
26c0: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
26d0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
26e0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
26f0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
2700: 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74 20 62 65  lose(C)] must be
2710: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a   either a NULL.*
2720: 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20  * pointer or an 
2730: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2740: 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65   pointer obtaine
2750: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
2760: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2770: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
2780: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
2790: 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e  pen_v2()], and n
27a0: 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c  ot previously cl
27b0: 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  osed..**.** Requ
27c0: 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
27d0: 32 30 31 31 5d 20 5b 48 31 32 30 31 32 5d 20 5b  2011] [H12012] [
27e0: 48 31 32 30 31 33 5d 20 5b 48 31 32 30 31 34 5d  H12013] [H12014]
27f0: 20 5b 48 31 32 30 31 35 5d 20 5b 48 31 32 30 31   [H12015] [H1201
2800: 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  9].*/.int sqlite
2810: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
2820: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
2830: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
2840: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
2850: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
2860: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
2870: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
2880: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
2890: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
28a0: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
28b0: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
28c0: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
28d0: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
28e0: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
28f0: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2900: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2910: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
2920: 74 65 72 66 61 63 65 20 7b 48 31 32 31 30 30 7d  terface {H12100}
2930: 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10000>.**.** 
2940: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
2950: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2960: 61 20 63 6f 6e 76 65 6e 69 65 6e 74 20 77 61 79  a convenient way
2970: 20 6f 66 20 72 75 6e 6e 69 6e 67 20 6f 6e 65 20   of running one 
2980: 6f 72 20 6d 6f 72 65 0a 2a 2a 20 53 51 4c 20 73  or more.** SQL s
2990: 74 61 74 65 6d 65 6e 74 73 20 77 69 74 68 6f 75  tatements withou
29a0: 74 20 68 61 76 69 6e 67 20 74 6f 20 77 72 69 74  t having to writ
29b0: 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64  e a lot of C cod
29c0: 65 2e 20 20 54 68 65 20 55 54 46 2d 38 20 65 6e  e.  The UTF-8 en
29d0: 63 6f 64 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  coded.** SQL sta
29e0: 74 65 6d 65 6e 74 73 20 61 72 65 20 70 61 73 73  tements are pass
29f0: 65 64 20 69 6e 20 61 73 20 74 68 65 20 73 65 63  ed in as the sec
2a00: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
2a10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2e   sqlite3_exec().
2a20: 0a 2a 2a 20 54 68 65 20 73 74 61 74 65 6d 65 6e  .** The statemen
2a30: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
2a40: 20 6f 6e 65 20 62 79 20 6f 6e 65 20 75 6e 74 69   one by one unti
2a50: 6c 20 65 69 74 68 65 72 20 61 6e 20 65 72 72 6f  l either an erro
2a60: 72 20 6f 72 0a 2a 2a 20 61 6e 20 69 6e 74 65 72  r or.** an inter
2a70: 72 75 70 74 20 69 73 20 65 6e 63 6f 75 6e 74 65  rupt is encounte
2a80: 72 65 64 2c 20 6f 72 20 75 6e 74 69 6c 20 74 68  red, or until th
2a90: 65 79 20 61 72 65 20 61 6c 6c 20 64 6f 6e 65 2e  ey are all done.
2aa0: 20 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65    The 3rd parame
2ab0: 74 65 72 0a 2a 2a 20 69 73 20 61 6e 20 6f 70 74  ter.** is an opt
2ac0: 69 6f 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 74  ional callback t
2ad0: 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hat is invoked o
2ae0: 6e 63 65 20 66 6f 72 20 65 61 63 68 20 72 6f 77  nce for each row
2af0: 20 6f 66 20 61 6e 79 20 71 75 65 72 79 0a 2a 2a   of any query.**
2b00: 20 72 65 73 75 6c 74 73 20 70 72 6f 64 75 63 65   results produce
2b10: 64 20 62 79 20 74 68 65 20 53 51 4c 20 73 74 61  d by the SQL sta
2b20: 74 65 6d 65 6e 74 73 2e 20 20 54 68 65 20 35 74  tements.  The 5t
2b30: 68 20 70 61 72 61 6d 65 74 65 72 20 74 65 6c 6c  h parameter tell
2b40: 73 20 77 68 65 72 65 0a 2a 2a 20 74 6f 20 77 72  s where.** to wr
2b50: 69 74 65 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  ite any error me
2b60: 73 73 61 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ssages..**.** Th
2b70: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
2b80: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
2b90: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
2ba0: 6d 65 74 65 72 20 69 73 20 68 65 6c 64 0a 2a 2a  meter is held.**
2bb0: 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
2bc0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2bd0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 6f  3_malloc()].  To
2be0: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
2bf0: 6c 65 61 6b 2c 0a 2a 2a 20 74 68 65 20 63 61 6c  leak,.** the cal
2c00: 6c 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f 6e  ling application
2c10: 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 5b 73 71   should call [sq
2c20: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
2c30: 20 61 6e 79 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   any error.** me
2c40: 73 73 61 67 65 20 72 65 74 75 72 6e 65 64 20 74  ssage returned t
2c50: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
2c60: 61 72 61 6d 65 74 65 72 20 77 68 65 6e 20 69 74  arameter when it
2c70: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
2c80: 69 6e 67 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  ing.** the error
2c90: 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
2ca0: 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2cb0: 6d 65 6e 74 20 69 6e 20 74 68 65 20 32 6e 64 20  ment in the 2nd 
2cc0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
2cd0: 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
2ce0: 72 69 6e 67 0a 2a 2a 20 6f 72 20 61 20 73 74 72  ring.** or a str
2cf0: 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 6f  ing containing o
2d00: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
2d10: 6e 64 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  nd comments, the
2d20: 6e 20 6e 6f 20 53 51 4c 0a 2a 2a 20 73 74 61 74  n no SQL.** stat
2d30: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
2d40: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74  ated and the dat
2d50: 61 62 61 73 65 20 69 73 20 6e 6f 74 20 63 68 61  abase is not cha
2d60: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nged..**.** The 
2d70: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
2d80: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
2d90: 65 6d 65 6e 74 65 64 20 69 6e 20 74 65 72 6d 73  emented in terms
2da0: 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
2db0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
2dc0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
2dd0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
2de0: 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 54 68  nalize()]..** Th
2df0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2e00: 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
2e10: 74 68 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74  thing to the dat
2e20: 61 62 61 73 65 20 74 68 61 74 20 63 61 6e 6e 6f  abase that canno
2e30: 74 20 62 65 20 64 6f 6e 65 0a 2a 2a 20 62 79 20  t be done.** by 
2e40: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e50: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
2e60: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
2e70: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e80: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
2e90: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
2ea0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2eb0: 5d 20 6d 75 73 74 20 62 65 20 61 6e 20 76 61 6c  ] must be an val
2ec0: 69 64 20 61 6e 64 20 6f 70 65 6e 0a 2a 2a 20 5b  id and open.** [
2ed0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ee0: 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ion]..**.** The 
2ef0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f00: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  ion must not be 
2f10: 63 6c 6f 73 65 64 20 77 68 69 6c 65 0a 2a 2a 20  closed while.** 
2f20: 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
2f30: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a   is running..**.
2f40: 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  ** The calling f
2f50: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  unction should u
2f60: 73 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  se [sqlite3_free
2f70: 28 29 5d 20 74 6f 20 66 72 65 65 0a 2a 2a 20 74  ()] to free.** t
2f80: 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 2a  he memory that *
2f90: 65 72 72 6d 73 67 20 69 73 20 6c 65 66 74 20 70  errmsg is left p
2fa0: 6f 69 6e 74 69 6e 67 20 61 74 20 6f 6e 63 65 20  ointing at once 
2fb0: 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
2fc0: 73 61 67 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  sage is no longe
2fd0: 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  r needed..**.** 
2fe0: 54 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  The SQL statemen
2ff0: 74 20 74 65 78 74 20 69 6e 20 74 68 65 20 32 6e  t text in the 2n
3000: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
3010: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 0a  sqlite3_exec()].
3020: 2a 2a 20 6d 75 73 74 20 72 65 6d 61 69 6e 20 75  ** must remain u
3030: 6e 63 68 61 6e 67 65 64 20 77 68 69 6c 65 20 5b  nchanged while [
3040: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
3050: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
3060: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
3070: 2a 2a 20 5b 48 31 32 31 30 31 5d 20 5b 48 31 32  ** [H12101] [H12
3080: 31 30 32 5d 20 5b 48 31 32 31 30 34 5d 20 5b 48  102] [H12104] [H
3090: 31 32 31 30 35 5d 20 5b 48 31 32 31 30 37 5d 20  12105] [H12107] 
30a0: 5b 48 31 32 31 31 30 5d 20 5b 48 31 32 31 31 33  [H12110] [H12113
30b0: 5d 20 5b 48 31 32 31 31 36 5d 0a 2a 2a 20 5b 48  ] [H12116].** [H
30c0: 31 32 31 31 39 5d 20 5b 48 31 32 31 32 32 5d 20  12119] [H12122] 
30d0: 5b 48 31 32 31 32 35 5d 20 5b 48 31 32 31 33 31  [H12125] [H12131
30e0: 5d 20 5b 48 31 32 31 33 34 5d 20 5b 48 31 32 31  ] [H12134] [H121
30f0: 33 37 5d 20 5b 48 31 32 31 33 38 5d 0a 2a 2f 0a  37] [H12138].*/.
3100: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
3110: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
3120: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3130: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3140: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3150: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3160: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3180: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3190: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
31a0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
31b0: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
31c0: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
31d0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
31e0: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
31f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3200: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3210: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
3220: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
3230: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
3240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3250: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
3260: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3270: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3280: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3290: 6c 74 20 43 6f 64 65 73 20 7b 48 31 30 32 31 30  lt Codes {H10210
32a0: 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45  } <S10700>.** KE
32b0: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
32c0: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
32d0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
32e0: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
32f0: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
3300: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
3310: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
3320: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
3330: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
3340: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
3350: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
3360: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
3370: 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  s success or fai
3380: 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  lure..**.** New 
3390: 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20  error codes may 
33a0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
33b0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
33c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  QLite..**.** See
33d0: 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
33e0: 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
33f0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3400: 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s].*/.#define SQ
3410: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3420: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3430: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3440: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3450: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3470: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3480: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3490: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
34a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34b0: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
34c0: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
34d0: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
34e0: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
34f0: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
3500: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
3510: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
3520: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3530: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
3540: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
3550: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
3560: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
3570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
3580: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
3590: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
35a0: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
35b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
35c0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
35d0: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
35e0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
35f0: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
3600: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
3610: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
3620: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
3630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3640: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
3650: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
3660: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
3670: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
3680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
3690: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
36a0: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
36b0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
36c0: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
36d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
36e0: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
36f0: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
3700: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
3710: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
3720: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
3730: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
3740: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
3750: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
3760: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3770: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
3780: 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e 20     /* NOT USED. 
3790: 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72 64 20  Table or record 
37a0: 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23 64 65  not found */.#de
37b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
37c0: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
37d0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
37e0: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
37f0: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
3800: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
3810: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
3820: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
3830: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
3840: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3850: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
3860: 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 2e  5   /* NOT USED.
3870: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
3880: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
3890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38a0: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
38b0: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
38c0: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
38d0: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
38e0: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
38f0: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
3900: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
3910: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
3920: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
3930: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
3940: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
3950: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3960: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
3970: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
3980: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69  to constraint vi
3990: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
39a0: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
39b0: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
39c0: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
39d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
39e0: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
39f0: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
3a00: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
3a10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3a20: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
3a30: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
3a40: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
3a50: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
3a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
3a70: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
3a80: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
3a90: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
3aa0: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
3ab0: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
3ac0: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
3ad0: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
3ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3af0: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
3b00: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
3b10: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
3b20: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
3b30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3b40: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
3b50: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
3b60: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
3b70: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
3b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
3b90: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
3ba0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
3bb0: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
3bc0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
3bd0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
3be0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
3bf0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
3c00: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
3c10: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
3c20: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
3c30: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3c40: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
3c50: 20 43 6f 64 65 73 20 7b 48 31 30 32 32 30 7d 20   Codes {H10220} 
3c60: 3c 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57  <S10700>.** KEYW
3c70: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
3c80: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
3c90: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
3ca0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
3cb0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
3cc0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
3cd0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
3ce0: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
3cf0: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
3d00: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
3d10: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
3d20: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
3d30: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
3d40: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
3d50: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
3d60: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
3d70: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
3d80: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
3d90: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
3da0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
3db0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
3dc0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
3dd0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
3de0: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
3df0: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
3e00: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
3e10: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
3e20: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
3e30: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
3e40: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
3e50: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
3e60: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
3e70: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
3e80: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
3e90: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
3ea0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
3eb0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
3ec0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
3ed0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
3ee0: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
3ef0: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
3f00: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
3f10: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
3f20: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
3f30: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
3f40: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
3f50: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
3f60: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
3f70: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
3f80: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
3f90: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
3fa0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
3fb0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
3fc0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
3fd0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
3fe0: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
3ff0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4000: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4010: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4020: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4030: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4040: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4050: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4060: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4070: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4080: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4090: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
40a0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
40b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
40c0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
40d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
40e0: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
40f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4100: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4120: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4130: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4140: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4150: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4160: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4170: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4180: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4190: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
41a0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
41b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
41c0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
41d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
41e0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
41f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4200: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4210: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4220: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4230: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4240: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4250: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4260: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4270: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4280: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4290: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
42a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
42b0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
42c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
42d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
42e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
42f0: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4300: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4310: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4320: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4330: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4340: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4350: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4360: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4370: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4380: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4390: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
43a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
43b0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
43c0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
43d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
43e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
43f0: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4400: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4410: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4420: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4430: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4440: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4450: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4460: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4470: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4480: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4490: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
44a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
44b0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
44c0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
44d0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
44e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
44f0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4500: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4510: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c  TE_LOCKED | (1<<
4520: 38 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  8) )../*.** CAPI
4530: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
4540: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
4550: 69 6f 6e 73 20 7b 48 31 30 32 33 30 7d 20 3c 48  ions {H10230} <H
4560: 31 31 31 32 30 3e 20 3c 48 31 32 37 30 30 3e 0a  11120> <H12700>.
4570: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20  **.** These bit 
4580: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e  values are inten
4590: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74  ded for use in t
45a0: 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65  he.** 3rd parame
45b0: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
45c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
45d0: 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20  nterface and.** 
45e0: 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  in the 4th param
45f0: 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65  eter to the xOpe
4600: 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a  n method of the.
4610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  ** [sqlite3_vfs]
4620: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
4630: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4640: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
4650: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
4660: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
4670: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
4680: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4690: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
46a0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
46b0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
46c0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
46d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
46e0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
46f0: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
4700: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
4710: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
4720: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4730: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
4740: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
4750: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
4760: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4770: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
4780: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
4790: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
47a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
47b0: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
47c0: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
47d0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
47f0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
4800: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
4810: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4830: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
4840: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
4850: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
4860: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4870: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
4880: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
4890: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
48a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
48b0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
48c0: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
48d0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
48e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
48f0: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
4900: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
4910: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
4920: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4930: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
4940: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
4950: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
4960: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4970: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
4980: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
4990: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
49a0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
49b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
49c0: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
49d0: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
49e0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
49f0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
4a00: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4a10: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
4a20: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
4a30: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
4a40: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
4a50: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
4a60: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
4a70: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
4a80: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
4a90: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a  pen_v2() */../*.
4aa0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
4ab0: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
4ac0: 69 63 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31  ics {H10240} <H1
4ad0: 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  1120>.**.** The 
4ae0: 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69 74  xDeviceCapabilit
4af0: 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ies method of th
4b00: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
4b10: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
4b20: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
4b30: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
4b40: 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65  ector of the the
4b50: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
4b60: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
4b70: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
4b80: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
4b90: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
4ba0: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
4bb0: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
4bc0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
4bd0: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
4be0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
4bf0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
4c00: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
4c10: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
4c20: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
4c30: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
4c40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
4c50: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
4c60: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
4c70: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
4c80: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
4c90: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
4ca0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
4cb0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
4cc0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
4cd0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
4ce0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
4cf0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
4d00: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
4d10: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
4d20: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
4d30: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
4d40: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
4d50: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
4d60: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
4d70: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
4d80: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
4d90: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
4da0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
4db0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
4dc0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
4dd0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
4de0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
4df0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
4e00: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
4e10: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64   xWrite()..*/.#d
4e20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4e30: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
4e40: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4e60: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
4e70: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
4e80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4e90: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
4ea0: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
4eb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4ec0: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
4ed0: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
4ee0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4ef0: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
4f00: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4f20: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
4f30: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
4f40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4f50: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
4f60: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
4f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4f80: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
4f90: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
4fa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4fb0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
4fc0: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
4fd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4fe0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
4ff0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
5000: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5010: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
5020: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f     0x00000400../
5030: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
5040: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
5050: 6c 73 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31  ls {H10250} <H11
5060: 31 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a  120> <H11310>.**
5070: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
5080: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
5090: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
50a0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
50b0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
50c0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
50d0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
50e0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
50f0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
5100: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
5110: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
5120: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
5130: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
5140: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
5150: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
5160: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5170: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
5180: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
5190: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
51a0: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
51b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
51c0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
51d0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
51e0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
51f0: 46 6c 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c  Flags {H10260} <
5200: 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68  H11120>.**.** Wh
5210: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5220: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5230: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5240: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5250: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5260: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5270: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5280: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5290: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
52a0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
52b0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
52c0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
52d0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
52e0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
52f0: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5300: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5310: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5320: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5330: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5340: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5350: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5360: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5370: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5380: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5390: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
53a0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
53b0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
53c0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
53d0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
53e0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
53f0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5400: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5410: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5420: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5440: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5450: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5460: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5470: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5480: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5490: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
54a0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
54b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
54c0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
54d0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31   File Handle {H1
54e0: 31 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a  1110} <S20110>.*
54f0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
5500: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
5510: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
5520: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
5530: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
5540: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
5550: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
5560: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
5570: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
5580: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
5590: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
55a0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
55b0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
55c0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
55d0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
55e0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
55f0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
5600: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
5610: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5620: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
5630: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
5640: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
5650: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
5660: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
5670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
5680: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
5690: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
56a0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
56b0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
56c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
56d0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
56e0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
56f0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
5700: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
5710: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
5720: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
5730: 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d 20 3c  bject {H11120} <
5740: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 45 76  S20110>.**.** Ev
5750: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
5760: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
5770: 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f  vfs] xOpen metho
5780: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
5790: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
57a0: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
57b0: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
57c0: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
57d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
57e0: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
57f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
5800: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
5810: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
5820: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
5830: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
5840: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
5850: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
5860: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
5870: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
5880: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
5890: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
58a0: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65  *.** If the xOpe
58b0: 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  n method sets th
58c0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
58d0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
58e0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
58f0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
5900: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
5910: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
5920: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
5930: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
5940: 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65  he xOpen reporte
5950: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
5960: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
5970: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
5980: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
5990: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
59a0: 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f  d xOpen.** is fo
59b0: 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73  r the xOpen to s
59c0: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
59d0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
59e0: 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ment to NULL..**
59f0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
5a00: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
5a10: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
5a20: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
5a30: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
5a40: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
5a50: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
5a60: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
5a70: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
5a80: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
5a90: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
5aa0: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
5ab0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
5ac0: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
5ad0: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
5ae0: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
5af0: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
5b00: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
5b10: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
5b20: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
5b30: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
5b40: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
5b50: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
5b60: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
5b70: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
5b80: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
5b90: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5ba0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
5bb0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
5bc0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
5bd0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
5be0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
5bf0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5c00: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
5c10: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
5c20: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
5c30: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
5c40: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
5c50: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
5c60: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
5c70: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
5c80: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
5c90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5ca0: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
5cb0: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
5cc0: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
5cd0: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
5ce0: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
5cf0: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
5d00: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
5d10: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
5d20: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
5d30: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
5d40: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
5d50: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
5d60: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
5d70: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
5d80: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
5d90: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
5da0: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
5db0: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
5dc0: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
5dd0: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
5de0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
5df0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
5e00: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
5e10: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
5e20: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
5e30: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
5e40: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
5e50: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
5e60: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
5e70: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
5e80: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
5e90: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
5ea0: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
5eb0: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
5ec0: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
5ed0: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
5ee0: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
5ef0: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
5f00: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
5f10: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
5f20: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
5f30: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
5f40: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
5f50: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
5f60: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
5f70: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
5f80: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
5f90: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
5fa0: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
5fb0: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
5fc0: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
5fd0: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
5fe0: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
5ff0: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
6000: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49   use..** A [SQLI
6010: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
6020: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  TE | list of opc
6030: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
6040: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
6050: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
6060: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
6070: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
6080: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
6090: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a  d use opcodes.**
60a0: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30   greater than 10
60b0: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c  0 to avoid confl
60c0: 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  icts..**.** The 
60d0: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65  xSectorSize() me
60e0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65  thod returns the
60f0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20   sector size of 
6100: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  the.** device th
6110: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65  at underlies the
6120: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74   file.  The sect
6130: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a  or size is the.*
6140: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20  * minimum write 
6150: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66  that can be perf
6160: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69  ormed without di
6170: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65  sturbing.** othe
6180: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  r bytes in the f
6190: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63  ile.  The xDevic
61a0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
61b0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
61c0: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f  urns a bit vecto
61d0: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68  r describing beh
61e0: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a  aviors of the.**
61f0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69   underlying devi
6200: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce:.**.** <ul>.*
6210: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6220: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20  OCAP_ATOMIC].** 
6230: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6240: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a  AP_ATOMIC512].**
6250: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6260: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a  CAP_ATOMIC1K].**
6270: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6280: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a  CAP_ATOMIC2K].**
6290: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
62a0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a  CAP_ATOMIC4K].**
62b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
62c0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a  CAP_ATOMIC8K].**
62d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
62e0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a  CAP_ATOMIC16K].*
62f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6300: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a  OCAP_ATOMIC32K].
6310: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d  IOCAP_ATOMIC64K]
6330: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6340: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6350: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ND].** <li> [SQL
6360: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6370: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  TIAL].** </ul>.*
6380: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
6390: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
63a0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
63b0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
63c0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
63d0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
63e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
63f0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
6400: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
6410: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
6420: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
6430: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
6440: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
6450: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
6460: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
6470: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
6480: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6490: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
64a0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
64b0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
64c0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
64d0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
64e0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
64f0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
6500: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
6510: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
6520: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
6530: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
6540: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6550: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
6560: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6570: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
6580: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
6590: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
65a0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
65b0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
65c0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
65d0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
65e0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
65f0: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
6600: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
6610: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
6620: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
6630: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
6640: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
6650: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
6660: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
6670: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
6680: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
6690: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
66a0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
66b0: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
66c0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
66d0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
66e0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
66f0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
6700: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
6710: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
6720: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
6730: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
6740: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
6750: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
6760: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
6770: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
6780: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
6790: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
67a0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
67b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
67c0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
67d0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
67e0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
67f0: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
6800: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
6810: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
6820: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
6830: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
6840: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
6850: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
6860: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
6870: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
6880: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
6890: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
68a0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
68b0: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
68c0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
68d0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
68e0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
68f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
6900: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
6910: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
6920: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
6930: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
6940: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
6950: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
6960: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
6970: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6980: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
6990: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74  le*);.  /* Addit
69a0: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
69b0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
69c0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
69d0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
69e0: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
69f0: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
6a00: 65 73 20 7b 48 31 31 33 31 30 7d 20 3c 53 33 30  es {H11310} <S30
6a10: 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  800>.**.** These
6a20: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
6a30: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
6a40: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
6a50: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
6a60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6a70: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6a80: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
6a90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
6aa0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
6ab0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
6ac0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6ad0: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
6ae0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
6af0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
6b00: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
6b10: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
6b20: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
6b30: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
6b40: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
6b50: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
6b60: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
6b70: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
6b80: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
6b90: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
6ba0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
6bb0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
6bc0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
6bd0: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
6be0: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
6bf0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
6c00: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
6c10: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
6c20: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
6c30: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
6c40: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
6c50: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
6c60: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23  is defined..*/.#
6c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
6c80: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
6c90: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
6ca0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
6cb0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23  OXYFILE      2.#
6cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
6cd0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
6ce0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6cf0: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
6d00: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a               4..
6d10: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6d20: 4d 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 48 31  Mutex Handle {H1
6d30: 37 31 31 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a  7110} <S20130>.*
6d40: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
6d50: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
6d60: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
6d70: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
6d80: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
6d90: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
6da0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
6db0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
6dc0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
6dd0: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
6de0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
6df0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
6e00: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
6e10: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
6e20: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
6e30: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
6e40: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
6e50: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
6e60: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
6e70: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
6e80: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
6e90: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
6ea0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
6eb0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6ec0: 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 31  face Object {H11
6ed0: 31 34 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a  140} <S20100>.**
6ee0: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
6ef0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
6f00: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
6f10: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
6f20: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
6f30: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
6f40: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
6f50: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
6f60: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
6f70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
6f80: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
6f90: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
6fa0: 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20   system"..**.** 
6fb0: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
6fc0: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
6fd0: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
6fe0: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
6ff0: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
7000: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
7010: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
7020: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
7030: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
7040: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
7050: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
7060: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
7070: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
7080: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
7090: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
70a0: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
70b0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
70c0: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
70d0: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
70e0: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
70f0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
7100: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
7110: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
7120: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
7130: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
7140: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
7150: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
7160: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
7170: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
7180: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
7190: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
71a0: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
71b0: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
71c0: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
71d0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
71e0: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
71f0: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
7200: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
7210: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
7220: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
7230: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
7240: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
7250: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
7260: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
7270: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
7280: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
7290: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
72a0: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
72b0: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
72c0: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
72d0: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
72e0: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
72f0: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
7300: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
7310: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
7320: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
7330: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
7340: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
7350: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
7360: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
7370: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
7380: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
7390: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
73a0: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
73b0: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
73c0: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
73d0: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
73e0: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
73f0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
7400: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
7410: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
7420: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
7430: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
7440: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
7450: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
7460: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
7470: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
7480: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
7490: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
74a0: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
74b0: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
74c0: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  dules..**.** SQL
74d0: 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74  ite will guarant
74e0: 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  ee that the zFil
74f0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
7500: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
7510: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
7520: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
7530: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
7540: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e  xFullPathname().
7550: 20 20 53 51 4c 69 74 65 20 66 75 72 74 68 65 72    SQLite further
7560: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
7570: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
7580: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
7590: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
75a0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
75b0: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
75c0: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
75d0: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
75e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
75f0: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
7600: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
7610: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
7620: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
7630: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
7640: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
7650: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
7660: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
7670: 72 20 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20  r is xOpen is a 
7680: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
7690: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
76a0: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
76b0: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
76c0: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65  r the file.  Whe
76d0: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
76e0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
76f0: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
7700: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
7710: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
7720: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
7730: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
7740: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
7750: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
7760: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
7770: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
7780: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
7790: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
77a0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
77b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
77c0: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
77d0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
77e0: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
77f0: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
7800: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
7810: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
7820: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
7830: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
7840: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
7850: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
7860: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
7870: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
7880: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
7890: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
78a0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
78b0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
78c0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
78d0: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  be set..**.** SQ
78e0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
78f0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
7900: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
7910: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
7920: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
7930: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
7940: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
7950: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
7960: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
7970: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
7980: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
7990: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
79a0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
79b0: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
79c0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
79d0: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
79e0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
79f0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
7a00: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7a10: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
7a20: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7a30: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
7a40: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  JOURNAL].** </ul
7a50: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  >.**.** The file
7a60: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
7a70: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
7a80: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
7a90: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
7aa0: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
7ab0: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
7ac0: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
7ad0: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
7ae0: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
7af0: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
7b00: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
7b10: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
7b20: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
7b30: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
7b40: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
7b50: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
7b60: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
7b70: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
7b80: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
7b90: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
7ba0: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
7bb0: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
7bc0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
7bd0: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
7be0: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
7bf0: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
7c00: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
7c10: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
7c20: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
7c30: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
7c40: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
7c50: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
7c60: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
7c70: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
7c80: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
7c90: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
7ca0: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
7cb0: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7cc0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
7cd0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7ce0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7cf0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
7d00: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
7d10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
7d20: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
7d30: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
7d40: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
7d50: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
7d60: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 54 68 65   is closed.  The
7d70: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
7d80: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
7d90: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
7da0: 54 45 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c  TEMP  databases,
7db0: 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f   journals and fo
7dc0: 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  r subjournals..*
7dd0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7de0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
7df0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
7e00: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
7e10: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
7e20: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
7e30: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
7e40: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
7e50: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
7e60: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
7e70: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
7e80: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
7e90: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
7ea0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
7eb0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
7ec0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
7ed0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
7ee0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
7ef0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
7f00: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
7f10: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
7f20: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
7f30: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
7f40: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
7f50: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
7f60: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
7f70: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
7f80: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
7f90: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
7fa0: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
7fb0: 2a 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46  * At least szOsF
7fc0: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
7fd0: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
7fe0: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
7ff0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
8000: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
8010: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
8020: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
8030: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
8040: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
8050: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
8060: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
8070: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
8080: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
8090: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
80a0: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
80b0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
80c0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
80d0: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
80e0: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
80f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8100: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
8110: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
8120: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
8130: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
8140: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
8150: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
8160: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
8170: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
8180: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
8190: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
81a0: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
81b0: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
81c0: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
81d0: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
81e0: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
81f0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
8200: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
8210: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
8220: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
8230: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
8240: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
8250: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
8260: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
8270: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
8280: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
8290: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
82a0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
82b0: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
82c0: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
82d0: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
82e0: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
82f0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
8300: 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ry..**.** SQLite
8310: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
8320: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
8330: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
8340: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
8350: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
8360: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
8370: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
8380: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
8390: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
83a0: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
83b0: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
83c0: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
83d0: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
83e0: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
83f0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
8400: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
8410: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
8420: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
8430: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
8440: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
8450: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
8460: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
8470: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
8480: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
8490: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
84a0: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
84b0: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
84c0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
84d0: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75  Sleep(), and xCu
84e0: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65  rrentTime() inte
84f0: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
8500: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
8510: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
8520: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
8530: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
8540: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
8550: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
8560: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
8570: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
8580: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
8590: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
85a0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
85b0: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
85c0: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
85d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
85e0: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
85f0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
8600: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
8610: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
8620: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
8630: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
8640: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
8650: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
8660: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
8670: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
8680: 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74  n.  The xCurrent
8690: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
86a0: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
86b0: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
86c0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
86d0: 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  e and time..**.*
86e0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
86f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
8700: 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74  ite3_vfs;.struct
8710: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
8720: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
8730: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
8740: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
8750: 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73  umber */.  int s
8760: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
8770: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
8780: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
8790: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
87a0: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
87b0: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
87c0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
87d0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
87e0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
87f0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
8800: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
8810: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8820: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
8830: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
8840: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
8850: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
8860: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
8870: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
8880: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
8890: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
88a0: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
88b0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
88c0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
88d0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
88e0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
88f0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
8900: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
8910: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
8920: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
8930: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
8940: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
8950: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
8960: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
8970: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
8980: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
8990: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
89a0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
89b0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
89c0: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
89d0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
89e0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
89f0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
8a00: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
8a10: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
8a20: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
8a30: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
8a40: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
8a50: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
8a60: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
8a70: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
8a80: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
8a90: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
8aa0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
8ab0: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
8ac0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
8ad0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
8ae0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
8af0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
8b00: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
8b10: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
8b20: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
8b30: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
8b40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
8b50: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
8b60: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
8b70: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
8b80: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65  char *);.  /* Ne
8b90: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
8ba0: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
8bb0: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
8bc0: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
8bd0: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
8be0: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
8bf0: 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d  is happens. */.}
8c00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8c10: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
8c20: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
8c30: 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31  hod {H11190} <H1
8c40: 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  1140>.**.** Thes
8c50: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
8c60: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
8c70: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
8c80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
8c90: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
8ca0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
8cb0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44  fs] object. {END
8cc0: 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  }  They determin
8cd0: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
8ce0: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
8cf0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
8d00: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
8d10: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
8d20: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
8d30: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
8d40: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
8d50: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
8d60: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
8d70: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
8d80: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
8d90: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
8da0: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
8db0: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f  r the file is bo
8dc0: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
8dd0: 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74  writable..** Wit
8de0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
8df0: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
8e00: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
8e10: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
8e20: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
8e30: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
8e40: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
8e50: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
8e60: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8e70: 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20  WRITE 1.#define 
8e80: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8e90: 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a  AD      2../*.**
8ea0: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
8eb0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
8ec0: 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30   Library {H10130
8ed0: 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30  } <S20000><S3010
8ee0: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
8ef0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8f00: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
8f10: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
8f20: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
8f30: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
8f40: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
8f50: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
8f60: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
8f70: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
8f80: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8f90: 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  ize()..**.** A c
8fa0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
8fb0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
8fc0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
8fd0: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
8fe0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
8ff0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9000: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
9010: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
9020: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
9030: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
9040: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
9050: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9060: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
9070: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
9080: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
9090: 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79  hutdown().  Only
90a0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
90b0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
90c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
90d0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
90e0: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
90f0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
9100: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a  armless no-ops..
9110: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
9120: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9130: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
9140: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
9150: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
9160: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
9170: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
9180: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
9190: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
91a0: 20 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65   Only.** an effe
91b0: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
91c0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
91d0: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
91e0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
91f0: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 20 74  ll other calls t
9200: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
9210: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
9220: 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  s no-ops..**.** 
9230: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
9240: 67 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  gs, sqlite3_init
9250: 69 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69  ialize() shall i
9260: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
9270: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
9280: 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f  ilarly, sqlite3_
9290: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68  shutdown().** sh
92a0: 61 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  all invoke sqlit
92b0: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
92c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
92d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
92e0: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
92f0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
9300: 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f  ss..** If for so
9310: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
9320: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9330: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
9340: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
9350: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
9360: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
9370: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
9380: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
9390: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
93a0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
93b0: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
93c0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
93d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
93e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
93f0: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
9400: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9410: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
9420: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
9430: 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
9440: 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
9450: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
9460: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
9470: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9480: 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
9490: 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
94a0: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
94b0: 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
94c0: 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
94d0: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
94e0: 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
94f0: 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
9500: 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
9510: 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
9520: 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
9530: 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
9540: 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65  * already.  Howe
9550: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
9560: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
9570: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
9580: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
9590: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
95a0: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
95b0: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
95c0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
95d0: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
95e0: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
95f0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
9600: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9610: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
9620: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
9630: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
9640: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
9650: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
9660: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
9670: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
9680: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
9690: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
96a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
96b0: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
96c0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
96d0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
96e0: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
96f0: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
9700: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
9710: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
9720: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
9730: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
9740: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
9750: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
9760: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
9770: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
9780: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
9790: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
97a0: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
97b0: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
97c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
97d0: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
97e0: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
97f0: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
9800: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
9810: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
9820: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
9830: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
9840: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
9850: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
9860: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
9870: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
9880: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
9890: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
98a0: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
98b0: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
98c0: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
98d0: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
98e0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
98f0: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
9900: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
9910: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
9920: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
9930: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
9940: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
9950: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
9960: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
9970: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
9980: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
9990: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
99a0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
99b0: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
99c0: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
99d0: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
99e0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
99f0: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
9a00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9a10: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
9a20: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
9a30: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
9a40: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
9a50: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
9a60: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
9a70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
9a80: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
9a90: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
9aa0: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
9ab0: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
9ac0: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
9ad0: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
9ae0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
9af0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9b00: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
9b10: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
9b20: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
9b30: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
9b40: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
9b50: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
9b60: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
9b70: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
9b80: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
9b90: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
9ba0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
9bb0: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
9bc0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
9bd0: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
9be0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
9bf0: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
9c00: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
9c10: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
9c20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
9c30: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
9c40: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
9c50: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
9c60: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9c70: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
9c80: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
9c90: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
9ca0: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
9cb0: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
9cc0: 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
9cd0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
9ce0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
9cf0: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
9d00: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
9d10: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
9d20: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
9d30: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
9d40: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
9d50: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
9d60: 62 72 61 72 79 20 7b 48 31 34 31 30 30 7d 20 3c  brary {H14100} <
9d70: 53 32 30 30 30 30 3e 3c 53 33 30 32 30 30 3e 0a  S20000><S30200>.
9d80: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
9d90: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
9da0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
9db0: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
9dc0: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
9dd0: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
9de0: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
9df0: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
9e00: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
9e10: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
9e20: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
9e30: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
9e40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
9e50: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
9e60: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
9e70: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
9e80: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
9e90: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
9ea0: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
9eb0: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
9ec0: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
9ed0: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
9ee0: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
9ef0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
9f00: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
9f10: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
9f20: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
9f30: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
9f40: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
9f50: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
9f60: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
9f70: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
9f80: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
9f90: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
9fa0: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
9fb0: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
9fc0: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
9fd0: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
9fe0: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
9ff0: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
a000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
a010: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
a020: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
a030: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a040: 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  ()]..** Note, ho
a050: 77 65 76 65 72 2c 20 74 68 61 74 20 73 71 6c 69  wever, that sqli
a060: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
a070: 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
a080: 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
a090: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
a0a0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
a0b0: 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
a0c0: 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
a0d0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
a0e0: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
a0f0: 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
a100: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
a110: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
a120: 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61  READ | configura
a130: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
a140: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
a150: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
a160: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
a170: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
a180: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
a190: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
a1a0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c  ding on the [SQL
a1b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
a1c0: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67  ETHREAD | config
a1d0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
a1e0: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
a1f0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
a200: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
a210: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
a220: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
a230: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
a240: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66 20  LITE_OK]..** If 
a250: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
a260: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
a270: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
a280: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
a290: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
a2a0: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
a2b0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
a2c0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
a2d0: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 31 30 33  ents:.** [H14103
a2e0: 5d 20 5b 48 31 34 31 30 36 5d 20 5b 48 31 34 31  ] [H14106] [H141
a2f0: 32 30 5d 20 5b 48 31 34 31 32 33 5d 20 5b 48 31  20] [H14123] [H1
a300: 34 31 32 36 5d 20 5b 48 31 34 31 32 39 5d 20 5b  4126] [H14129] [
a310: 48 31 34 31 33 32 5d 20 5b 48 31 34 31 33 35 5d  H14132] [H14135]
a320: 0a 2a 2a 20 5b 48 31 34 31 33 38 5d 20 5b 48 31  .** [H14138] [H1
a330: 34 31 34 31 5d 20 5b 48 31 34 31 34 34 5d 20 5b  4141] [H14144] [
a340: 48 31 34 31 34 37 5d 20 5b 48 31 34 31 35 30 5d  H14147] [H14150]
a350: 20 5b 48 31 34 31 35 33 5d 20 5b 48 31 34 31 35   [H14153] [H1415
a360: 36 5d 20 5b 48 31 34 31 35 39 5d 0a 2a 2a 20 5b  6] [H14159].** [
a370: 48 31 34 31 36 32 5d 20 5b 48 31 34 31 36 35 5d  H14162] [H14165]
a380: 20 5b 48 31 34 31 36 38 5d 0a 2a 2f 0a 53 51 4c   [H14168].*/.SQL
a390: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
a3a0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e   int sqlite3_con
a3b0: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
a3c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a3d0: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
a3e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20  se connections  
a3f0: 7b 48 31 34 32 30 30 7d 20 3c 53 32 30 30 30 30  {H14200} <S20000
a400: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
a410: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  L.**.** The sqli
a420: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
a430: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
a440: 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
a450: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
a460: 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
a470: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
a480: 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
a490: 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
a4a0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a4b0: 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
a4c0: 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
a4d0: 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
a4e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a4f0: 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
a500: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
a510: 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20  ument).  The.** 
a520: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
a530: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
a540: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69  n only be used i
a550: 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
a560: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
a570: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
a580: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
a590: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a  lite3_open()],.*
a5a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
a5b0: 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  6()], or [sqlite
a5c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a  3_open_v2()].  .
a5d0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
a5e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
a5f0: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
a600: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
a610: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
a620: 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67   verb - an integ
a630: 65 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64  er code that ind
a640: 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61  icates what.** a
a650: 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
a660: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a670: 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
a680: 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f  igured..** The o
a690: 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74  nly choice for t
a6a0: 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51  his value is [SQ
a6b0: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
a6c0: 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77  OKASIDE]..** New
a6d0: 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c   verbs are likel
a6e0: 79 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e  y to be added in
a6f0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
a700: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41   of SQLite..** A
a710: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
a720: 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68  nts depend on th
a730: 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 52 65  e verb..**.** Re
a740: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
a750: 48 31 34 32 30 33 5d 20 5b 48 31 34 32 30 36 5d  H14203] [H14206]
a760: 20 5b 48 31 34 32 30 39 5d 20 5b 48 31 34 32 31   [H14209] [H1421
a770: 32 5d 20 5b 48 31 34 32 31 35 5d 0a 2a 2f 0a 53  2] [H14215].*/.S
a780: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
a790: 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  AL int sqlite3_d
a7a0: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
a7b0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
a7c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a7d0: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
a7e0: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
a7f0: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a  0155} <S20120>.*
a800: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
a810: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
a820: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
a830: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
a840: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
a850: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
a860: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
a870: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
a880: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
a890: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
a8a0: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
a8b0: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
a8c0: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
a8d0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
a8e0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
a8f0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
a900: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
a910: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
a920: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
a930: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
a940: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
a950: 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
a960: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
a970: 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
a980: 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
a990: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
a9a0: 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
a9b0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
a9c0: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
a9d0: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
a9e0: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
a9f0: 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
aa00: 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
aa10: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
aa20: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
aa30: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
aa40: 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
aa50: 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
aa60: 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
aa70: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
aa80: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
aa90: 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
aaa0: 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
aab0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
aac0: 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
aad0: 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
aae0: 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
aaf0: 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
ab00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
ab10: 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
ab20: 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
ab30: 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
ab40: 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
ab50: 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
ab60: 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
ab70: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
ab80: 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
ab90: 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
aba0: 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
abb0: 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
abc0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
abd0: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
abe0: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
abf0: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
ac00: 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
ac10: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
ac20: 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
ac30: 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
ac40: 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
ac50: 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
ac60: 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
ac70: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
ac80: 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72   xMalloc and xFr
ac90: 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
aca0: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
acb0: 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
acc0: 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
acd0: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
ace0: 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
acf0: 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68  he xRealloc meth
ad00: 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  od must work lik
ad10: 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d  e realloc() from
ad20: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
ad30: 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 20  library.** with 
ad40: 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 68  the exception th
ad50: 61 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e 64  at if the second
ad60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 65   argument to xRe
ad70: 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a  alloc is zero,.*
ad80: 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20  * xRealloc must 
ad90: 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20  be a no-op - it 
ada0: 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d  must not perform
adb0: 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20   any allocation 
adc0: 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69  or.** deallocati
add0: 6f 6e 2e 20 20 53 51 4c 69 74 65 20 67 75 61 72  on.  SQLite guar
ade0: 61 6e 74 65 65 64 73 20 74 68 61 74 20 74 68 65  anteeds that the
adf0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
ae00: 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
ae10: 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
ae20: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
ae30: 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
ae40: 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73  oundup..** And s
ae50: 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 65  o in cases where
ae60: 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 73   xRoundup always
ae70: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74   returns a posit
ae80: 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78  ive number,.** x
ae90: 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66  Realloc can perf
aea0: 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 74  orm exactly as t
aeb0: 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
aec0: 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  ary realloc() an
aed0: 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e  d.** still be in
aee0: 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 68   compliance with
aef0: 20 74 68 69 73 20 73 70 65 63 69 66 69 63 61 74   this specificat
af00: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  ion..**.** xSize
af10: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
af20: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
af30: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
af40: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
af50: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
af60: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
af70: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
af80: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
af90: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
afa0: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
afb0: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
afc0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
afd0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
afe0: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
aff0: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
b000: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
b010: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
b020: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b030: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
b040: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
b050: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
b060: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
b070: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
b080: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
b090: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
b0a0: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
b0b0: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
b0c0: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
b0d0: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
b0e0: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
b0f0: 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
b100: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b110: 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
b120: 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
b130: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
b140: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
b150: 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
b160: 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
b170: 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
b180: 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
b190: 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
b1a0: 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
b1b0: 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
b1c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
b1d0: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
b1e0: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
b1f0: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
b200: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
b210: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
b220: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
b230: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
b240: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
b250: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
b260: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
b270: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
b280: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
b290: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
b2a0: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
b2b0: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
b2c0: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
b2d0: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
b2e0: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
b2f0: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
b300: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
b310: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
b320: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
b330: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
b340: 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
b350: 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
b360: 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
b370: 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
b380: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
b390: 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
b3a0: 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
b3b0: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
b3c0: 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
b3d0: 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
b3e0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b3f0: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
b400: 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
b410: 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
b420: 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
b430: 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
b440: 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
b450: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
b460: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
b470: 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
b480: 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
b490: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
b4a0: 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
b4b0: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
b4c0: 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
b4d0: 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
b4e0: 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
b4f0: 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
b500: 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
b510: 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
b520: 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
b530: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
b540: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
b550: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
b560: 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
b570: 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
b580: 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
b590: 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
b5a0: 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
b5b0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
b5c0: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
b5d0: 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
b5e0: 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
b5f0: 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
b600: 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
b610: 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
b620: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
b630: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
b640: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
b650: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
b660: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
b670: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
b680: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
b690: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
b6a0: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
b6b0: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
b6c0: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
b6d0: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
b6e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
b6f0: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
b700: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
b710: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
b720: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
b730: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
b740: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
b750: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
b760: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
b770: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
b780: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
b790: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
b7a0: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
b7b0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
b7c0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
b7d0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
b7e0: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
b7f0: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
b800: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
b810: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
b820: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
b830: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
b840: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
b850: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
b860: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
b870: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
b880: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
b890: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
b8a0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b8b0: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
b8c0: 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d  Options {H10160}
b8d0: 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50   <S20000>.** EXP
b8e0: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
b8f0: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
b900: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
b910: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
b920: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
b930: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
b940: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
b950: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
b960: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
b970: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
b980: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
b990: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
b9a0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
b9b0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
b9c0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
b9d0: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
b9e0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
b9f0: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
ba00: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
ba10: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
ba20: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
ba30: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
ba40: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
ba50: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
ba60: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
ba70: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
ba80: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
ba90: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
baa0: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
bab0: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
bac0: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
bad0: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
bae0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
baf0: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
bb00: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
bb10: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
bb20: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
bb30: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
bb40: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
bb50: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
bb60: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61  This option disa
bb70: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
bb80: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
bb90: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
bba0: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
bbb0: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
bbc0: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
bbd0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
bbe0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
bbf0: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
bc00: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
bc10: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
bc20: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
bc30: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62  his option disab
bc40: 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
bc50: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
bc60: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
bc70: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
bc80: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
bc90: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
bca0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
bcb0: 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
bcc0: 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
bcd0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
bce0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
bcf0: 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
bd00: 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
bd10: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
bd20: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
bd30: 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
bd40: 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
bd50: 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
bd60: 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
bd70: 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
bd80: 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
bd90: 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
bda0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
bdb0: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
bdc0: 20 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61    See the [threa
bdd0: 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f  ding mode].** do
bde0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
bdf0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
be00: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  mation.</dd>.**.
be10: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
be20: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
be30: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
be40: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
be50: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
be60: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
be70: 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
be80: 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
be90: 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
bea0: 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
beb0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
bec0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
bed0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
bee0: 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
bef0: 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
bf00: 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
bf10: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
bf20: 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
bf30: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
bf40: 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
bf50: 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
bf60: 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
bf70: 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
bf80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
bf90: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
bfa0: 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
bfb0: 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
bfc0: 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
bfd0: 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
bfe0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bff0: 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
c000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
c010: 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
c020: 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
c030: 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
c040: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
c050: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
c060: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
c070: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
c080: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
c090: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c0a0: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
c0b0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
c0c0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
c0d0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
c0e0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
c0f0: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
c100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
c110: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
c120: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
c130: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
c140: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
c150: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
c160: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
c170: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
c180: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
c190: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c1a0: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
c1b0: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  nto SQLite.</dd>
c1c0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c1d0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
c1e0: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OC</dt>.** <dd>T
c1f0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c200: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
c210: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
c220: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
c230: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
c240: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
c250: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
c260: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
c270: 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
c280: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
c290: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
c2a0: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
c2b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
c2c0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
c2d0: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
c2e0: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
c2f0: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
c300: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
c310: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
c320: 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
c330: 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
c340: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
c350: 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
c360: 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
c370: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e  or example.</dd>
c380: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c390: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
c3a0: 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  US</dt>.** <dd>T
c3b0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c3c0: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
c3d0: 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
c3e0: 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
c3f0: 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
c400: 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
c410: 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
c420: 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
c430: 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
c440: 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64  atistics. When d
c450: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
c460: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
c470: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
c480: 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  .** non-operatio
c490: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
c4a0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
c4b0: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
c4c0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
c4d0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
c4e0: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
c4f0: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
c500: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  heap_limit()].**
c510: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
c520: 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20  _status()].**   
c530: 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  </ul>.** </dd>.*
c540: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
c550: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
c560: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
c570: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
c580: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
c590: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
c5a0: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
c5b0: 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
c5c0: 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  y.  There are th
c5d0: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
c5e0: 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
c5f0: 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
c600: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
c610: 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
c620: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
c630: 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
c640: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
c650: 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
c660: 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
c670: 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
c680: 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
c690: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
c6a0: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
c6b0: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
c6c0: 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54  ultiple of 16. T
c6d0: 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20  he sz parameter 
c6e0: 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20  should be a few 
c6f0: 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20  bytes.** larger 
c700: 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20  than the actual 
c710: 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65  scratch space re
c720: 71 75 69 72 65 64 20 64 75 65 20 74 6f 20 69 6e  quired due to in
c730: 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e  ternal overhead.
c740: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
c750: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
c760: 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
c770: 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
c780: 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
c790: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
c7a0: 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  emory..** SQLite
c7b0: 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
c7c0: 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
c7d0: 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63  ch buffer at onc
c7e0: 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f  e per thread, so
c7f0: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
c800: 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 63  set to the expec
c810: 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
c820: 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20  er of threads.  
c830: 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65  The sz.** parame
c840: 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20  ter should be 6 
c850: 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f  times the size o
c860: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
c870: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
c880: 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66  ..** Scratch buf
c890: 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61 73  fers are used as
c8a0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 72   part of the btr
c8b0: 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61  ee balance opera
c8c0: 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65  tion.  If.** The
c8d0: 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20   btree balancer 
c8e0: 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
c8f0: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
c900: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
c910: 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75  by.** scratch bu
c920: 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73  ffers or if no s
c930: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73 70  cratch buffer sp
c940: 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64  ace is specified
c950: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
c960: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
c970: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f  3_malloc()] to o
c980: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
c990: 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a   it needs.</dd>.
c9a0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c9b0: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
c9c0: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
c9d0: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
c9e0: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
c9f0: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
ca00: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
ca10: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
ca20: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
ca30: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
ca40: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
ca50: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
ca60: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
ca70: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
ca80: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
ca90: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
caa0: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
cab0: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
cac0: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
cad0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
cae0: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
caf0: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
cb00: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
cb10: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
cb20: 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
cb30: 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
cb40: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
cb50: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
cb60: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
cb70: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
cb80: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
cb90: 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
cba0: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
cbb0: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
cbc0: 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
cbd0: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
cbe0: 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
cbf0: 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
cc00: 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
cc10: 20 68 65 61 64 65 72 2e 20 20 54 68 65 20 70 61   header.  The pa
cc20: 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69  ge header size i
cc30: 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73  s 20 to 40 bytes
cc40: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a   depending on.**
cc50: 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74   the host archit
cc60: 65 63 74 75 72 65 2e 20 20 49 74 20 69 73 20 68  ecture.  It is h
cc70: 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
cc80: 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
cc90: 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b  emory,.** to mak
cca0: 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f  e sz a little to
ccb0: 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69  o large.  The fi
ccc0: 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
ccd0: 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20  should point to 
cce0: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66  an allocation of
ccf0: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
cd00: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
cd10: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  ** SQLite will u
cd20: 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
cd30: 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
cd40: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
cd50: 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
cd60: 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
cd70: 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
cd80: 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
cd90: 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64 64  o cache.  If add
cda0: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
cdb0: 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
cdc0: 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
cdd0: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
cde0: 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
cdf0: 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
ce00: 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
ce10: 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
ce20: 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
ce30: 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
ce40: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
ce50: 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f   might use one o
ce60: 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20  r more of the N 
ce70: 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20  buffers to hold 
ce80: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75  .** memory accou
ce90: 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f  nting informatio
cea0: 6e 2e 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  n. The pointer i
ceb0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
cec0: 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
ced0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
cee0: 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
cef0: 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
cf00: 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
cf10: 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
cf20: 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
cf30: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
cf40: 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
cf50: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
cf60: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
cf70: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
cf80: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
cf90: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
cfa0: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
cfb0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
cfc0: 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
cfd0: 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
cfe0: 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
cff0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
d000: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
d010: 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
d020: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
d030: 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38   arguments: An 8
d040: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
d050: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
d060: 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
d070: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
d080: 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
d090: 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
d0a0: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
d0b0: 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72  e..** If the fir
d0c0: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
d0d0: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
d0e0: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
d0f0: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
d100: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
d110: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
d120: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
d130: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
d140: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
d150: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
d160: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
d170: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
d180: 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a  LLOC].  If the.*
d190: 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
d1a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
d1b0: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
d1c0: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
d1d0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
d1e0: 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
d1f0: 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
d200: 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
d210: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
d220: 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
d230: 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
d240: 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
d250: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
d260: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
d270: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
d280: 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
d290: 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
d2a0: 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
d2b0: 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
d2c0: 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
d2d0: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
d2e0: 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
d2f0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
d300: 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
d310: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
d320: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
d330: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
d340: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
d350: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
d360: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
d370: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
d380: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
d390: 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
d3a0: 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
d3b0: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
d3c0: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
d3d0: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
d3e0: 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
d3f0: 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
d400: 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  QLite.</dd>.**.*
d410: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d420: 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
d430: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
d440: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
d450: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
d460: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
d470: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
d480: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
d490: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
d4a0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
d4b0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
d4c0: 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
d4d0: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
d4e0: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
d4f0: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
d500: 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  tex routines..**
d510: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
d520: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
d530: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
d540: 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
d550: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
d560: 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
d570: 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
d580: 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
d590: 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
d5a0: 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
d5b0: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64  for example.</dd
d5c0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d5d0: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
d5e0: 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
d5f0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d600: 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
d610: 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
d620: 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65  he default.** me
d630: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
d640: 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d 69  lookaside optimi
d650: 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 72  zation.  The fir
d660: 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
d670: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
d680: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
d690: 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
d6a0: 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
d6b0: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
d6c0: 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
d6d0: 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
d6e0: 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f  nection.  This o
d6f0: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
d700: 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
d710: 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
d720: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42    The [SQLITE_DB
d730: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
d740: 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71  ].** verb to [sq
d750: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
d760: 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
d770: 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
d780: 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
d790: 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
d7a0: 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
d7b0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
d7c0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
d7d0: 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
d7e0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
d7f0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
d800: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
d810: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
d820: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
d830: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
d840: 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
d850: 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69   specifies the i
d860: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61  nterface.** to a
d870: 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
d880: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
d890: 6e 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  n.  SQLite makes
d8a0: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
d8b0: 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
d8c0: 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
d8d0: 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
d8e0: 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
d8f0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
d900: 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f  NFIG_GETPCACHE</
d910: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
d920: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
d930: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
d940: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
d950: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
d960: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
d970: 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  ds] object.  SQL
d980: 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
d990: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
d9a0: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
d9b0: 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
d9c0: 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
d9d0: 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
d9e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d9f0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
da00: 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
da10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
da20: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
da30: 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
da40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
da50: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
da60: 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
da70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
da80: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
da90: 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
daa0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
dab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
dac0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
dad0: 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
dae0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
daf0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
db00: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
db10: 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
db20: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
db30: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
db40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
db50: 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
db60: 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
db70: 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
db80: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
db90: 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
dba0: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
dbb0: 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
dbc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
dbd0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
dbe0: 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
dbf0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dc00: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
dc10: 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
dc20: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
dc30: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
dc40: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
dc50: 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
dc60: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
dc70: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
dc80: 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
dc90: 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
dca0: 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
dcb0: 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
dcc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
dcd0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
dce0: 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
dcf0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dd00: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
dd10: 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71         14  /* sq
dd20: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
dd30: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
dd40: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
dd50: 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
dd60: 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
dd70: 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f  e_methods* */../
dd80: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
dd90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
dda0: 69 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53  ions {H10170} <S
ddb0: 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20000>.** EXPERI
ddc0: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
ddd0: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
dde0: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
ddf0: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
de00: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
de10: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
de20: 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
de30: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
de40: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
de50: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
de60: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
de70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
de80: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
de90: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
dea0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
deb0: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
dec0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
ded0: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
dee0: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
def0: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
df00: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
df10: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
df20: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
df30: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
df40: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
df50: 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
df60: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
df70: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
df80: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
df90: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
dfa0: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
dfb0: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
dfc0: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
dfd0: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
dfe0: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
dff0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
e000: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
e010: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
e020: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
e030: 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
e040: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
e050: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
e060: 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
e070: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
e080: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
e090: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
e0a0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
e0b0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e0c0: 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
e0d0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
e0e0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
e0f0: 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
e100: 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66  to an memory buf
e110: 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
e120: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
e130: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
e140: 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55  gument may be NU
e150: 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
e160: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
e170: 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
e180: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
e190: 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
e1a0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
e1b0: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
e1c0: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
e1d0: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
e1e0: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
e1f0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 61   and the third a
e200: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
e210: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
e220: 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
e230: 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
e240: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
e250: 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
e260: 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
e270: 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
e280: 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
e290: 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
e2a0: 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
e2b0: 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
e2c0: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
e2d0: 62 6f 75 6e 64 61 72 79 2e 20 20 49 66 20 74 68  boundary.  If th
e2e0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
e2f0: 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  t is not.** a mu
e300: 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
e310: 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 20 72 6f  is internally ro
e320: 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
e330: 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a  e next smaller.*
e340: 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  * multiple of 8.
e350: 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
e360: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
e370: 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  SIDE]</dd>.**.**
e380: 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
e390: 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
e3a0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
e3b0: 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
e3c0: 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a  t int */.../*.**
e3d0: 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
e3e0: 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
e3f0: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
e400: 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 30  es {H12200} <S10
e410: 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  700>.**.** The s
e420: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
e430: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
e440: 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
e450: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
e460: 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
e470: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
e480: 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 65  e of SQLite. The
e490: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
e4a0: 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
e4b0: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
e4c0: 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
e4d0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 63   compatibility c
e4e0: 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a  onsiderations..*
e4f0: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
e500: 73 3a 0a 2a 2a 20 5b 48 31 32 32 30 31 5d 20 5b  s:.** [H12201] [
e510: 48 31 32 32 30 32 5d 0a 2a 2f 0a 69 6e 74 20 73  H12202].*/.int s
e520: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
e530: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
e540: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
e550: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
e560: 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
e570: 52 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c  Rowid {H12220} <
e580: 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61  S10700>.**.** Ea
e590: 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53  ch entry in an S
e5a0: 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20  QLite table has 
e5b0: 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
e5c0: 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
e5d0: 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
e5e0: 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
e5f0: 22 5d 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  "]. The rowid is
e600: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
e610: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
e620: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
e630: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
e640: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
e650: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
e660: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
e670: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
e680: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
e690: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
e6a0: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
e6b0: 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
e6c0: 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
e6d0: 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
e6e0: 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
e6f0: 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
e700: 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  wid..**.** This 
e710: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
e720: 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
e730: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
e740: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
e750: 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
e760: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
e770: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e780: 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
e790: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
e7a0: 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66    If no successf
e7b0: 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
e7c0: 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
e7d0: 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
e7e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
e7f0: 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
e800: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b 49  ..**.** If an [I
e810: 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
e820: 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
e830: 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  then the [rowid]
e840: 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
e850: 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72  .** row is retur
e860: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
e870: 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
e880: 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75  he trigger is ru
e890: 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
e8a0: 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
e8b0: 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
e8c0: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
e8d0: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
e8e0: 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
e8f0: 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
e900: 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74  ted before the t
e910: 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a  rigger fired..**
e920: 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d 20  .** An [INSERT] 
e930: 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
e940: 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
e950: 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
e960: 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
e970: 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
e980: 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
e990: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
e9a0: 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
e9b0: 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54  ne.  Thus INSERT
e9c0: 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
e9d0: 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
e9e0: 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
e9f0: 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
ea00: 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
ea10: 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
ea20: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
ea30: 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
ea40: 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
ea50: 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20  on fails.  When 
ea60: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
ea70: 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
ea80: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
ea90: 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
eaa0: 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
eab0: 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
eac0: 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
ead0: 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
eae0: 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
eaf0: 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
eb00: 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
eb10: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
eb20: 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
eb30: 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
eb40: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
eb50: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
eb60: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
eb70: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
eb80: 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
eb90: 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
eba0: 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
ebb0: 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
ebc0: 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
ebd0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 52 65  d back..**.** Re
ebe0: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
ebf0: 48 31 32 32 32 31 5d 20 5b 48 31 32 32 32 33 5d  H12221] [H12223]
ec00: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
ec10: 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
ec20: 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
ec30: 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
ec40: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
ec50: 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
ec60: 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
ec70: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
ec80: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
ec90: 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
eca0: 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
ecb0: 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
ecc0: 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
ecd0: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
ece0: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
ecf0: 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
ed00: 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
ed10: 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
ed20: 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
ed30: 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
ed40: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
ed50: 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
ed60: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
ed70: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
ed80: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
ed90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
eda0: 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
edb0: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b   Rows Modified {
edc0: 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30 30 3e  H12240} <S10600>
edd0: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
ede0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
edf0: 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
ee00: 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
ee10: 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
ee20: 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
ee30: 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
ee40: 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
ee50: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
ee60: 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
ee70: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ee80: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
ee90: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
eea0: 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e  er..** Only chan
eeb0: 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
eec0: 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
eed0: 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
eee0: 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
eef0: 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
ef00: 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
ef10: 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
ef20: 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
ef30: 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f   triggers or [fo
ef40: 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
ef50: 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
ef60: 65 64 2e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  ed. Use the.** [
ef70: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
ef80: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
ef90: 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
efa0: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
efb0: 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
efc0: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
efd0: 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
efe0: 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
eff0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 43 68 61  tions..**.** Cha
f000: 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
f010: 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65  hat are simulate
f020: 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44  d by an [INSTEAD
f030: 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20   OF trigger].** 
f040: 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
f050: 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c    Only real tabl
f060: 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
f070: 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 20 22  unted..**.** A "
f080: 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61  row change" is a
f090: 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e   change to a sin
f0a0: 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e  gle row of a sin
f0b0: 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75  gle table.** cau
f0c0: 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54  sed by an INSERT
f0d0: 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44  , DELETE, or UPD
f0e0: 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ATE statement.  
f0f0: 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65  Rows that.** are
f100: 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65   changed as side
f110: 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50   effects of [REP
f120: 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
f130: 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
f140: 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
f150: 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f  processing, [DRO
f160: 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20  P TABLE], or by 
f170: 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63  any other.** mec
f180: 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63  hanisms do not c
f190: 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72  ount as direct r
f1a0: 6f 77 20 63 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a  ow changes..**.*
f1b0: 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
f1c0: 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
f1d0: 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
f1e0: 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
f1f0: 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
f200: 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
f210: 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
f220: 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
f230: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
f240: 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
f250: 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
f260: 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
f270: 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
f280: 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
f290: 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
f2a0: 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
f2b0: 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
f2c0: 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
f2d0: 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
f2e0: 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
f2f0: 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
f300: 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
f310: 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
f320: 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
f330: 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
f340: 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** Calling [sql
f350: 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
f360: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
f370: 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
f380: 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
f390: 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
f3a0: 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ntext..**.** Thi
f3b0: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
f3c0: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
f3d0: 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
f3e0: 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
f3f0: 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
f400: 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
f410: 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
f420: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
f430: 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
f440: 2e 0a 2a 2a 0a 2a 2a 20 54 68 75 73 2c 20 77 68  ..**.** Thus, wh
f450: 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  en called from t
f460: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68  he top level, th
f470: 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
f480: 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65  rns the.** numbe
f490: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20  r of changes in 
f4a0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
f4b0: 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
f4c0: 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61  or DELETE.** tha
f4d0: 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20  t also occurred 
f4e0: 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  at the top level
f4f0: 2e 20 20 57 69 74 68 69 6e 20 74 68 65 20 62 6f  .  Within the bo
f500: 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
f510: 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
f520: 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
f530: 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
f540: 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
f550: 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
f560: 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
f570: 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
f580: 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
f590: 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
f5a0: 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
f5b0: 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
f5c0: 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
f5d0: 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
f5e0: 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
f5f0: 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
f600: 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
f610: 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
f620: 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
f630: 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
f640: 78 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  xt..**.** See al
f650: 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
f660: 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
f670: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 20 74   interface and t
f680: 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
f690: 6e 67 65 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2a  nges pragma]..**
f6a0: 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
f6b0: 3a 0a 2a 2a 20 5b 48 31 32 32 34 31 5d 20 5b 48  :.** [H12241] [H
f6c0: 31 32 32 34 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20  12243].**.** If 
f6d0: 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
f6e0: 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
f6f0: 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
f700: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
f710: 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
f720: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
f730: 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
f740: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
f750: 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
f760: 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
f770: 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
f780: 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
f790: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
f7a0: 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
f7b0: 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
f7c0: 4d 6f 64 69 66 69 65 64 20 7b 48 31 32 32 36 30  Modified {H12260
f7d0: 7d 20 3c 53 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10600>.**.**
f7e0: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   This function r
f7f0: 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
f800: 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73  r of row changes
f810: 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45   caused by [INSE
f820: 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d  RT],.** [UPDATE]
f830: 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
f840: 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68  tements since th
f850: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
f860: 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e  ection] was open
f870: 65 64 2e 0a 2a 2a 20 54 68 65 20 63 6f 75 6e 74  ed..** The count
f880: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68   includes all ch
f890: 61 6e 67 65 73 20 66 72 6f 6d 20 61 6c 6c 20 5b  anges from all [
f8a0: 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
f8b0: 20 74 72 69 67 67 65 72 5d 20 0a 2a 2a 20 63 6f   trigger] .** co
f8c0: 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67  ntexts and chang
f8d0: 65 73 20 6d 61 64 65 20 62 79 20 5b 66 6f 72 65  es made by [fore
f8e0: 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
f8f0: 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68  . However,.** th
f900: 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  e count does not
f910: 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
f920: 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
f930: 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  nt [REPLACE] con
f940: 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20  straints,.** do 
f950: 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f  rollbacks or ABO
f960: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f  RT processing, o
f970: 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70  r [DROP TABLE] p
f980: 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a  rocessing.  The.
f990: 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  ** count does no
f9a0: 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f  t include rows o
f9b0: 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72  f views that fir
f9c0: 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  e an [INSTEAD OF
f9d0: 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68   trigger],.** th
f9e0: 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54  ough if the INST
f9f0: 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d  EAD OF trigger m
fa00: 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20  akes changes of 
fa10: 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63  its own, those c
fa20: 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63  hanges .** are c
fa30: 6f 75 6e 74 65 64 2e 0a 2a 2a 20 54 68 65 20 63  ounted..** The c
fa40: 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74  hanges are count
fa50: 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
fa60: 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
fa70: 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 0a 2a   makes them is.*
fa80: 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65  * completed (whe
fa90: 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
faa0: 68 61 6e 64 6c 65 20 69 73 20 70 61 73 73 65 64  handle is passed
fab0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
fac0: 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
fad0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
fae0: 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
faf0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
fb00: 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
fb10: 61 63 65 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b  ace and the.** [
fb20: 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
fb30: 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  agma]..**.** Req
fb40: 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
fb50: 31 32 32 36 31 5d 20 5b 48 31 32 32 36 33 5d 0a  12261] [H12263].
fb60: 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
fb70: 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
fb80: 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
fb90: 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
fba0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
fbb0: 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
fbc0: 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
fbd0: 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
fbe0: 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
fbf0: 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
fc00: 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
fc10: 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ngful..*/.int sq
fc20: 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
fc30: 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
fc40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
fc50: 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67  Interrupt A Long
fc60: 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 20 7b  -Running Query {
fc70: 48 31 32 32 37 30 7d 20 3c 53 33 30 35 30 30 3e  H12270} <S30500>
fc80: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
fc90: 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
fca0: 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
fcb0: 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
fcc0: 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
fcd0: 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
fce0: 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
fcf0: 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
fd00: 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
fd10: 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
fd20: 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
fd30: 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
fd40: 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
fd50: 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
fd60: 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
fd70: 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
fd80: 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
fd90: 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
fda0: 20 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63   It is safe to c
fdb0: 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
fdc0: 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64   from a thread d
fdd0: 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68  ifferent from th
fde0: 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74  e.** thread that
fdf0: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75   is currently ru
fe00: 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61  nning the databa
fe10: 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42  se operation.  B
fe20: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20  ut it.** is not 
fe30: 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
fe40: 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
fe50: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fe60: 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69  ction] that.** i
fe70: 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68  s closed or migh
fe80: 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73  t close before s
fe90: 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
fea0: 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  () returns..**.*
feb0: 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72  * If an SQL oper
fec0: 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
fed0: 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
fee0: 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
fef0: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
ff00: 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
ff10: 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
ff20: 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
ff30: 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
ff40: 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
ff50: 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
ff60: 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
ff70: 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70 65 72 61  .** An SQL opera
ff80: 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
ff90: 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
ffa0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
ffb0: 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49 66 20 74  ERRUPT]..** If t
ffc0: 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
ffd0: 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
ffe0: 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
fff0: 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
10000 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
10010 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
10020 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
10030 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
10040 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
10050 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
10060 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
10070 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
10080 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
10090 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
100a0 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
100b0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
100c0 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
100d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
100e0 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 41  ] D complete.  A
100f0 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
10100 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
10110 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
10120 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
10130 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
10140 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
10150 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
10160 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
10170 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
10180 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
10190 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
101a0 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
101b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
101c0 63 61 6c 6c 2e 20 20 4e 65 77 20 53 51 4c 20 73  call.  New SQL s
101d0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
101e0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
101f0 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20  ter the running 
10200 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20  statement count 
10210 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
10220 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64  .** not effected
10230 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
10240 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20  interrupt()..** 
10250 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
10260 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
10270 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
10280 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
10290 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
102a0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
102b0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
102c0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
102d0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
102e0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
102f0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
10300 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
10310 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  urns..**.** Requ
10320 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
10330 32 32 37 31 5d 20 5b 48 31 32 32 37 32 5d 0a 2a  2271] [H12272].*
10340 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
10350 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
10360 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
10370 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
10380 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
10390 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
103a0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
103b0 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
103c0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
103d0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
103e0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
103f0 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
10400 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
10410 6c 65 74 65 20 7b 48 31 30 35 31 30 7d 20 3c 53  lete {H10510} <S
10420 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  70200>.**.** The
10430 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
10440 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
10450 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
10460 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
10470 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
10480 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
10490 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
104a0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
104b0 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
104c0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
104d0 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
104e0 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
104f0 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
10500 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 54   for parsing.  T
10510 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
10520 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e  turn 1 if the in
10530 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70  put string.** ap
10540 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f  pears to be a co
10550 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65  mplete SQL state
10560 6d 65 6e 74 2e 20 20 41 20 73 74 61 74 65 6d 65  ment.  A stateme
10570 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
10580 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
10590 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
105a0 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
105b0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
105c0 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
105d0 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
105e0 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
105f0 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  t.  Semicolons t
10600 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
10610 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
10620 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
10630 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
10640 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
10650 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
10660 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
10670 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
10680 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
10690 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
106a0 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
106b0 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
106c0 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
106d0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 57 68 69  terminator.  Whi
106e0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
106f0 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
10700 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
10710 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
10720 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  red..**.** These
10730 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
10740 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
10750 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
10760 65 2e 20 20 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  e.  If a.** memo
10770 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
10780 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
10790 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
107a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
107b0 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20  routines do not 
107c0 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74  parse the SQL st
107d0 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a  atements thus.**
107e0 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74   will not detect
107f0 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69   syntactically i
10800 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a  ncorrect SQL..**
10810 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 68 61  .** If SQLite ha
10820 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
10830 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
10840 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10850 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
10860 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
10870 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
10880 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
10890 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
108a0 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
108b0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
108c0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
108d0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
108e0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
108f0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
10900 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
10910 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
10920 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
10930 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
10940 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
10950 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
10960 73 20 63 6f 6d 70 6c 65 74 65 2e 0a 2a 2a 0a 2a  s complete..**.*
10970 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20  * Requirements: 
10980 5b 48 31 30 35 31 31 5d 20 5b 48 31 30 35 31 32  [H10511] [H10512
10990 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ].**.** The inpu
109a0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
109b0 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
109c0 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
109d0 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
109e0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
109f0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
10a00 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
10a10 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
10a20 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
10a30 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
10a40 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
10a50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
10a60 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
10a70 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71  ar *sql);.int sq
10a80 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
10a90 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
10aa0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10ab0 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
10ac0 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
10ad0 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
10ae0 72 6f 72 73 20 7b 48 31 32 33 31 30 7d 20 3c 53  rors {H12310} <S
10af0 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  40400>.**.** Thi
10b00 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
10b10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
10b20 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
10b30 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
10b40 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
10b50 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
10b60 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
10b70 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
10b80 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
10b90 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
10ba0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62 75 73 79  *.** If the busy
10bb0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
10bc0 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
10bd0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
10be0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
10bf0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
10c00 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
10c10 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
10c20 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65 20 62 75   lock. If the bu
10c30 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
10c40 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
10c50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 69   the callback wi
10c60 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ll be invoked wi
10c70 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
10c80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
10c90 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
10ca0 65 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  e handler is a c
10cb0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
10cc0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
10cd0 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
10ce0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
10cf0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
10d00 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
10d10 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
10d20 65 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  e handler callba
10d30 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
10d40 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
10d50 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
10d60 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
10d70 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
10d80 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 49 66 20  king event.  If 
10d90 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
10da0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
10db0 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
10dc0 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
10dd0 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
10de0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
10df0 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
10e00 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
10e10 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
10e20 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 74 68  turned..** If th
10e30 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
10e40 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
10e50 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70  n another attemp
10e60 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20  t.** is made to 
10e70 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
10e80 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  e for reading an
10e90 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65  d the cycle repe
10ea0 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ats..**.** The p
10eb0 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73  resence of a bus
10ec0 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e  y handler does n
10ed0 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  ot guarantee tha
10ee0 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76  t it will be inv
10ef0 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  oked.** when the
10f00 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65  re is lock conte
10f10 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c 69 74 65  ntion. If SQLite
10f20 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
10f30 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
10f40 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
10f50 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
10f60 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
10f70 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
10f80 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
10f90 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
10fa0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
10fb0 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
10fc0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
10fd0 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
10fe0 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
10ff0 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
11000 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
11010 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
11020 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
11030 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
11040 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
11050 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
11060 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
11070 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
11080 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
11090 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
110a0 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
110b0 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
110c0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
110d0 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
110e0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
110f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
11100 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
11110 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
11120 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
11130 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
11140 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
11150 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
11160 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
11170 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
11180 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
11190 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
111a0 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
111b0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
111c0 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
111d0 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
111e0 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
111f0 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
11200 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
11210 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
11220 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
11230 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
11240 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
11250 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66  d..**.** The def
11260 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
11270 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
11280 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55  * The [SQLITE_BU
11290 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
112a0 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
112b0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
112c0 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
112d0 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
112e0 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
112f0 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
11300 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
11310 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
11320 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
11330 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
11340 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
11350 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
11360 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
11370 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
11380 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
11390 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
113a0 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
113b0 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
113c0 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
113d0 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
113e0 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
113f0 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
11400 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
11410 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
11420 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
11430 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
11440 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
11450 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
11460 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
11470 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
11480 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
11490 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
114a0 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
114b0 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
114c0 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
114d0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
114e0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
114f0 5d 2e 20 20 54 68 69 73 20 65 72 72 6f 72 20 63  ].  This error c
11500 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
11510 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
11520 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
11530 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
11540 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
11550 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
11560 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
11570 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
11580 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
11590 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
115a0 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
115b0 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
115c0 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
115d0 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
115e0 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e 20 6f 6e  .** There can on
115f0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
11600 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69  usy handler defi
11610 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ned for each.** 
11620 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11630 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20  tion].  Setting 
11640 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c  a new busy handl
11650 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a  er clears any.**
11660 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
11670 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74 65 20 74  handler.  Note t
11680 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
11690 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
116a0 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73  t()].** will als
116b0 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74  o set or clear t
116c0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
116d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
116e0 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
116f0 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
11700 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
11710 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
11720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
11730 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
11740 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79  sy handler.  Any
11750 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
11760 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
11770 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
11780 2a 20 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  * .** Requiremen
11790 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 31 31 5d 20  ts:.** [H12311] 
117a0 5b 48 31 32 33 31 32 5d 20 5b 48 31 32 33 31 34  [H12312] [H12314
117b0 5d 20 5b 48 31 32 33 31 36 5d 20 5b 48 31 32 33  ] [H12316] [H123
117c0 31 38 5d 0a 2a 2a 0a 2a 2a 20 41 20 62 75 73 79  18].**.** A busy
117d0 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
117e0 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
117f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
11800 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
11810 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
11820 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
11830 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
11840 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
11850 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
11860 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
11870 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
11880 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
11890 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 20 7b  A Busy Timeout {
118a0 48 31 32 33 34 30 7d 20 3c 53 34 30 34 31 30 3e  H12340} <S40410>
118b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
118c0 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
118d0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
118e0 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
118f0 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
11900 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
11910 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
11920 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
11930 6f 63 6b 65 64 2e 20 20 54 68 65 20 68 61 6e 64  ocked.  The hand
11940 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
11950 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
11960 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
11970 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
11980 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
11990 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
119a0 64 2e 20 7b 48 31 32 33 34 33 7d 20 41 66 74 65  d. {H12343} Afte
119b0 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  r "ms" milliseco
119c0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
119d0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
119e0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
119f0 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
11a00 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
11a10 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
11a20 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
11a30 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a  ERR_BLOCKED]..**
11a40 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73  .** Calling this
11a50 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
11a60 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
11a70 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
11a80 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
11a90 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
11aa0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ers..**.** There
11ab0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
11ac0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
11ad0 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
11ae0 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
11af0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
11b00 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
11b10 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
11b20 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
11b30 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
11b40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
11b50 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
11b60 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
11b70 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
11b80 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
11b90 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
11ba0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
11bb0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 34  ments:.** [H1234
11bc0 31 5d 20 5b 48 31 32 33 34 33 5d 20 5b 48 31 32  1] [H12343] [H12
11bd0 33 34 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  344].*/.int sqli
11be0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
11bf0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
11c00 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
11c10 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
11c20 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
11c30 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 20 7b 48  nning Queries {H
11c40 31 32 33 37 30 7d 20 3c 53 31 30 30 30 30 3e 0a  12370} <S10000>.
11c50 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
11c60 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
11c70 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
11c80 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
11c90 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
11ca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
11cb0 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
11cc0 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
11cd0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
11ce0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
11cf0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
11d00 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
11d10 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
11d20 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
11d30 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
11d40 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
11d50 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
11d60 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
11d70 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
11d80 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
11d90 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
11da0 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
11db0 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
11dc0 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
11dd0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
11de0 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
11df0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
11e00 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
11e10 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
11e20 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
11e30 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
11e40 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
11e50 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
11e60 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
11e70 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
11e80 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
11e90 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
11ea0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
11eb0 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
11ec0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
11ed0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
11ee0 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
11ef0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
11f00 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
11f10 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
11f20 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
11f30 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
11f40 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
11f50 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
11f60 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
11f70 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
11f80 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
11f90 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
11fa0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
11fb0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
11fc0 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
11fd0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
11fe0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11ff0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
12000 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
12010 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
12020 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
12030 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
12040 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
12050 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
12060 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
12070 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
12080 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20 65 78 61  .**.** As an exa
12090 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
120a0 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
120b0 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
120c0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
120d0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
120e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
120f0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
12100 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
12110 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
12120 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
12130 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
12140 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
12150 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
12160 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
12170 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
12180 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
12190 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
121a0 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
121b0 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
121c0 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
121d0 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
121e0 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
121f0 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
12200 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
12210 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
12220 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
12230 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
12240 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
12250 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
12260 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
12270 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
12280 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
12290 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
122a0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
122b0 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
122c0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
122d0 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
122e0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
122f0 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
12300 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
12310 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
12320 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
12330 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
12340 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
12350 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
12360 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
12370 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
12380 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
12390 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
123a0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
123b0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
123c0 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
123d0 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
123e0 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
123f0 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
12400 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
12410 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
12420 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
12430 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
12440 72 61 6d 65 74 65 72 2e 20 20 49 74 20 72 65 74  rameter.  It ret
12450 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
12460 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
12470 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
12480 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
12490 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
124a0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
124b0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
124c0 75 73 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74  using the result
124d0 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 70  , it should.** p
124e0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20  ass the pointer 
124f0 74 6f 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  to the result ta
12500 62 6c 65 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ble to sqlite3_f
12510 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
12520 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
12530 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
12540 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
12550 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
12560 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
12570 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
12580 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
12590 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
125a0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
125b0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
125c0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
125d0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
125e0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
125f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
12600 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
12610 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
12620 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
12630 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
12640 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12650 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
12660 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
12670 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
12680 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
12690 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
126a0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
126b0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
126c0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
126d0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
126e0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
126f0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
12700 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
12710 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
12720 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
12730 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
12740 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
12750 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
12760 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
12770 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
12780 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
12790 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
127a0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
127b0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
127c0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
127d0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
127e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   or [sqlite3_err
127f0 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  msg()]..**.** Re
12800 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
12810 48 31 32 33 37 31 5d 20 5b 48 31 32 33 37 33 5d  H12371] [H12373]
12820 20 5b 48 31 32 33 37 34 5d 20 5b 48 31 32 33 37   [H12374] [H1237
12830 36 5d 20 5b 48 31 32 33 37 39 5d 20 5b 48 31 32  6] [H12379] [H12
12840 33 38 32 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  382].*/.int sqli
12850 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
12860 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
12870 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
12880 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
12890 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
128a0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
128b0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
128c0 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
128d0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
128e0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
128f0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
12900 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
12910 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
12920 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
12930 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
12940 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
12950 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
12960 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
12970 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
12980 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
12990 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
129a0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
129b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
129c0 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
129d0 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
129e0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
129f0 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
12a00 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31  ng Functions {H1
12a10 37 34 30 30 7d 20 3c 53 37 30 30 30 30 3e 3c 53  7400} <S70000><S
12a20 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  20000>.**.** The
12a30 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
12a40 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
12a50 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
12a60 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
12a70 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
12a80 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
12a90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
12aa0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
12ab0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
12ac0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
12ad0 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
12ae0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
12af0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
12b00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12b10 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
12b20 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
12b30 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
12b40 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
12b50 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
12b60 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 42 6f 74  e3_free()].  Bot
12b70 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
12b80 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
12b90 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
12ba0 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
12bb0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
12bc0 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
12bd0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
12be0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
12bf0 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74 65 33 5f  *.** In sqlite3_
12c00 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
12c10 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
12c20 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
12c30 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
12c40 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
12c50 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
12c60 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
12c70 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
12c80 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
12c90 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
12ca0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
12cb0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
12cc0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
12cd0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
12ce0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
12cf0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
12d00 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
12d10 69 6e 74 66 28 29 2e 20 20 54 68 69 73 20 69 73  intf().  This is
12d20 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
12d30 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
12d40 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
12d50 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
12d60 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
12d70 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 4e 6f  mpatibility.  No
12d80 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c  te also that sql
12d90 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
12da0 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ** returns a poi
12db0 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66  nter to its buff
12dc0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  er instead of th
12dd0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
12de0 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c  haracters actual
12df0 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  ly written into 
12e00 74 68 65 20 62 75 66 66 65 72 2e 20 20 57 65 20  the buffer.  We 
12e10 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
12e20 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
12e30 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
12e40 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
12e50 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
12e60 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
12e70 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
12e80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
12e90 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
12ea0 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
12eb0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
12ec0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
12ed0 20 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   As long as the 
12ee0 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
12ef0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
12f00 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
12f10 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
12f20 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
12f30 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
12f40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 54  o-terminated.  T
12f50 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
12f60 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
12f70 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
12f80 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
12f90 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
12fa0 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
12fb0 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
12fc0 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
12fd0 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
12fe0 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
12ff0 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
13000 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  acters..**.** Th
13010 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
13020 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
13030 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
13040 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
13050 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
13060 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
13070 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
13080 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
13090 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
130a0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
130b0 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
130c0 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
130d0 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
130e0 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  ", and "%z" opti
130f0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 25  ons..**.** The %
13100 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
13110 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
13120 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
13130 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a  null-terminated.
13140 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
13150 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
13160 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
13170 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
13180 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
13190 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
131a0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
131b0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 20  string literal. 
131c0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
131d0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
131e0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
131f0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
13200 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
13210 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
13220 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
13230 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
13240 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
13250 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
13260 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
13270 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
13280 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
13290 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
132a0 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
132b0 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
132c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
132d0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
132e0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
132f0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
13300 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
13310 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
13320 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
13330 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
13340 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
13350 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
13360 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
13370 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
13380 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
13390 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
133a0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
133b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
133c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
133d0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
133e0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
133f0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
13400 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
13410 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
13420 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
13430 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
13440 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
13450 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
13460 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
13470 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
13480 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
13490 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
134a0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
134b0 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
134c0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
134d0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
134e0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
134f0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
13500 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
13510 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
13520 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
13530 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
13540 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
13550 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
13560 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
13570 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
13580 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
13590 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
135a0 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
135b0 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
135c0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
135d0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
135e0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
135f0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
13600 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 54  literal..**.** T
13610 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
13620 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
13630 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
13640 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
13650 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
13660 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
13670 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
13680 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
13690 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
136a0 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
136b0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
136c0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
136d0 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
136e0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
136f0 6e 67 6c 65 20 71 75 6f 74 65 73 29 20 69 6e 20  ngle quotes) in 
13700 70 6c 61 63 65 20 6f 66 20 74 68 65 20 25 51 20  place of the %Q 
13710 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20 66 6f 72  option.  So, for
13720 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
13730 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
13740 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
13750 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
13760 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
13770 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
13780 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
13790 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
137a0 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
137b0 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
137c0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
137d0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
137e0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
137f0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
13800 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
13810 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
13820 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
13830 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
13840 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
13850 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
13860 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
13870 2a 2a 20 54 68 65 20 22 25 7a 22 20 66 6f 72 6d  ** The "%z" form
13880 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f  atting option wo
13890 72 6b 73 20 65 78 61 63 74 6c 79 20 6c 69 6b 65  rks exactly like
138a0 20 22 25 73 22 20 77 69 74 68 20 74 68 65 0a 2a   "%s" with the.*
138b0 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
138c0 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
138d0 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
138e0 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
138f0 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
13900 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
13910 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
13920 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 20 7b 45  input string. {E
13930 4e 44 7d 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ND}.**.** Requir
13940 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 34  ements:.** [H174
13950 30 33 5d 20 5b 48 31 37 34 30 36 5d 20 5b 48 31  03] [H17406] [H1
13960 37 34 30 37 5d 0a 2a 2f 0a 63 68 61 72 20 2a 73  7407].*/.char *s
13970 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
13980 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
13990 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
139a0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
139b0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
139c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
139d0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
139e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
139f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13a00 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
13a10 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 20  ation Subsystem 
13a20 7b 48 31 37 33 30 30 7d 20 3c 53 32 30 30 30 30  {H17300} <S20000
13a30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  >.**.** The SQLi
13a40 74 65 20 63 6f 72 65 20 20 75 73 65 73 20 74 68  te core  uses th
13a50 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
13a60 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
13a70 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
13a80 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
13a90 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
13aa0 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
13ab0 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
13ac0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
13ad0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
13ae0 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
13af0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
13b00 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
13b10 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
13b20 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
13b30 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
13b40 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
13b50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13b60 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
13b70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
13b80 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
13b90 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
13ba0 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
13bb0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
13bc0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49 66 20 73  rameter..** If s
13bd0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
13be0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
13bf0 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
13c00 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
13c10 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
13c20 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 74 68   pointer.  If th
13c30 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
13c40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
13c50 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
13c60 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
13c70 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
13c80 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
13c90 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
13ca0 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
13cb0 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f  free() with a po
13cc0 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79  inter previously
13cd0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
13ce0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13cf0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
13d00 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74  loc() releases t
13d10 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a  hat memory so.**
13d20 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62   that it might b
13d30 65 20 72 65 75 73 65 64 2e 20 20 54 68 65 20 73  e reused.  The s
13d40 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
13d50 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
13d60 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
13d70 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
13d80 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
13d90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
13da0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
13db0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
13dc0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
13dd0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
13de0 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
13df0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
13e00 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
13e10 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
13e20 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
13e30 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
13e40 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
13e50 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
13e60 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
13e70 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
13e80 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
13e90 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
13ea0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
13eb0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
13ec0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
13ed0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
13ee0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
13ef0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
13f00 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
13f10 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
13f20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
13f30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
13f40 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
13f50 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
13f60 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
13f70 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
13f80 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
13f90 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
13fa0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
13fb0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
13fc0 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
13fd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
13fe0 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
13ff0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
14000 65 72 2e 20 20 49 66 20 74 68 65 20 66 69 72 73  er.  If the firs
14010 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
14020 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
14030 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
14040 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
14050 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
14060 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
14070 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
14080 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
14090 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
140a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
140b0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 49 66  realloc()..** If
140c0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
140d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
140e0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
140f0 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
14100 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
14110 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
14120 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
14130 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
14140 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
14150 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14160 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
14170 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 73 71  realloc()..** sq
14180 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
14190 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
141a0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
141b0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
141c0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
141d0 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
141e0 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
141f0 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
14200 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20 69 73 20  ble..** If M is 
14210 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
14220 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
14230 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20  , then min(N,M) 
14240 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20  bytes.** of the 
14250 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
14260 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f   are copied into
14270 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
14280 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65  f buffer returne
14290 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
142a0 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68  realloc() and th
142b0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
142c0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
142d0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
142e0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
142f0 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
14300 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
14310 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
14320 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 72  .** The memory r
14330 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
14340 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
14350 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14360 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
14370 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
14380 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
14390 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a  ndary. {END}.**.
143a0 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 69  ** The default i
143b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
143c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
143d0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
143e0 20 75 73 65 73 0a 2a 2a 20 74 68 65 20 6d 61 6c   uses.** the mal
143f0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
14400 20 61 6e 64 20 66 72 65 65 28 29 20 70 72 6f 76   and free() prov
14410 69 64 65 64 20 62 79 20 74 68 65 20 73 74 61 6e  ided by the stan
14420 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
14430 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48 6f 77 65  ** {H17382} Howe
14440 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
14450 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
14460 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 45  the.** SQLITE_ME
14470 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e 4e 4e 4e  MORY_SIZE=<i>NNN
14480 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f 63 65 73  </i> C preproces
14490 73 6f 72 20 6d 61 63 72 6f 20 28 77 68 65 72 65  sor macro (where
144a0 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a 2a 20 69   <i>NNN</i>.** i
144b0 73 20 61 6e 20 69 6e 74 65 67 65 72 29 2c 20 74  s an integer), t
144c0 68 65 6e 20 53 51 4c 69 74 65 20 63 72 65 61 74  hen SQLite creat
144d0 65 20 61 20 73 74 61 74 69 63 20 61 72 72 61 79  e a static array
144e0 20 6f 66 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20   of at least.** 
144f0 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79 74 65 73  <i>NNN</i> bytes
14500 20 69 6e 20 73 69 7a 65 20 61 6e 64 20 75 73 65   in size and use
14510 73 20 74 68 61 74 20 61 72 72 61 79 20 66 6f 72  s that array for
14520 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
14530 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  mic.** memory al
14540 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
14550 7b 45 4e 44 7d 20 20 41 64 64 69 74 69 6f 6e 61  {END}  Additiona
14560 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
14570 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 6d 61  or options.** ma
14580 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
14590 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
145a0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
145b0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
145c0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
145d0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
145e0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
145f0 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
14600 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
14610 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
14620 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
14630 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
14640 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
14650 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
14660 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
14670 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
14680 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
14690 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
146a0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
146b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64  ..**.** The Wind
146c0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
146d0 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   layer calls.** 
146e0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
146f0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
14700 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
14710 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
14720 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
14730 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
14740 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
14750 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
14760 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
14770 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
14780 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
14790 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
147a0 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
147b0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72  cation errors ar
147c0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
147d0 2a 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f  ** they are repo
147e0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
147f0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
14800 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
14810 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
14820 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
14830 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
14840 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 30 33 5d 20  ts:.** [H17303] 
14850 5b 48 31 37 33 30 34 5d 20 5b 48 31 37 33 30 35  [H17304] [H17305
14860 5d 20 5b 48 31 37 33 30 36 5d 20 5b 48 31 37 33  ] [H17306] [H173
14870 31 30 5d 20 5b 48 31 37 33 31 32 5d 20 5b 48 31  10] [H17312] [H1
14880 37 33 31 35 5d 20 5b 48 31 37 33 31 38 5d 0a 2a  7315] [H17318].*
14890 2a 20 5b 48 31 37 33 32 31 5d 20 5b 48 31 37 33  * [H17321] [H173
148a0 32 32 5d 20 5b 48 31 37 33 32 33 5d 0a 2a 2a 0a  22] [H17323].**.
148b0 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
148c0 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
148d0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
148e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
148f0 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
14900 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
14910 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
14920 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
14930 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
14940 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
14950 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
14960 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
14970 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
14980 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
14990 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
149a0 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
149b0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
149c0 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
149d0 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
149e0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
149f0 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
14a00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
14a10 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
14a20 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
14a30 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
14a40 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
14a50 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  *sqlite3_realloc
14a60 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f  (void*, int);.vo
14a70 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
14a80 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
14a90 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
14aa0 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
14ab0 74 69 63 73 20 7b 48 31 37 33 37 30 7d 20 3c 53  tics {H17370} <S
14ac0 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20 53 51 4c  30210>.**.** SQL
14ad0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
14ae0 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
14af0 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
14b00 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
14b10 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14b20 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
14b30 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
14b40 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
14b50 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
14b60 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
14b70 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
14b80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
14b90 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 52 65  system..**.** Re
14ba0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
14bb0 48 31 37 33 37 31 5d 20 5b 48 31 37 33 37 33 5d  H17371] [H17373]
14bc0 20 5b 48 31 37 33 37 34 5d 20 5b 48 31 37 33 37   [H17374] [H1737
14bd0 35 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  5].*/.sqlite3_in
14be0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
14bf0 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
14c00 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
14c10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
14c20 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
14c30 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
14c40 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
14c50 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
14c60 72 61 74 6f 72 20 7b 48 31 37 33 39 30 7d 20 3c  rator {H17390} <
14c70 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 51  S20000>.**.** SQ
14c80 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
14c90 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
14ca0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
14cb0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
14cc0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
14cd0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
14ce0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
14cf0 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
14d00 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
14d10 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
14d20 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
14d30 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
14d40 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
14d50 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
14d60 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
14d70 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
14d80 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
14d90 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
14da0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
14db0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
14dc0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
14dd0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
14de0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
14df0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 74  *.** A call to t
14e00 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
14e10 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
14e20 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
14e30 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 54 68  ffer P..**.** Th
14e40 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
14e50 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
14e60 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
14e70 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
14e80 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14e90 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
14ea0 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
14eb0 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
14ec0 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
14ed0 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
14ee0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
14ef0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
14f00 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20 73 75 62  t..** On all sub
14f10 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
14f20 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
14f30 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
14f40 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
14f50 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
14f60 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
14f70 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
14f80 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
14f90 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  ethod..**.** Req
14fa0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
14fb0 31 37 33 39 32 5d 0a 2a 2f 0a 76 6f 69 64 20 73  17392].*/.void s
14fc0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
14fd0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
14fe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
14ff0 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
15000 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
15010 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 35 30 30  allbacks {H12500
15020 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70100>.**.**
15030 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
15040 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72  gisters a author
15050 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
15060 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
15070 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
15080 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
15090 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
150a0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
150b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
150c0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
150d0 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
150e0 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
150f0 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
15100 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
15110 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
15120 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
15130 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
15140 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
15150 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
15160 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 41  pare16_v2()].  A
15170 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
15180 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
15190 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
151a0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
151b0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
151c0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
151d0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
151e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
151f0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
15200 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
15210 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
15220 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20 61 75 74  llowed.  The aut
15230 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15240 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
15250 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f  n [SQLITE_OK] to
15260 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f   allow the actio
15270 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  n, [SQLITE_IGNOR
15280 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74  E] to disallow t
15290 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61  he.** specific a
152a0 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20  ction but allow 
152b0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
152c0 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f  t to continue to
152d0 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c   be.** compiled,
152e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
152f0 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65  ] to cause the e
15300 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d  ntire SQL statem
15310 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a  ent to be.** rej
15320 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72  ected with an er
15330 72 6f 72 2e 20 20 49 66 20 74 68 65 20 61 75 74  ror.  If the aut
15340 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15350 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
15360 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
15370 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
15380 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
15390 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
153a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
153b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
153c0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
153d0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
153e0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
153f0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
15400 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
15410 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
15420 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
15430 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
15440 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
15450 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
15460 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
15470 2e 20 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  .  When the call
15480 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
15490 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
154a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
154b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
154c0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
154d0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
154e0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
154f0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
15500 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
15510 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
15520 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
15530 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  d. .**.** The fi
15540 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
15550 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
15560 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
15570 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
15580 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
15590 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
155a0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
155b0 65 72 66 61 63 65 2e 20 54 68 65 20 73 65 63 6f  erface. The seco
155c0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
155d0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
155e0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
155f0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
15600 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
15610 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
15620 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
15630 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
15640 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 74 68  ed. The third th
15650 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
15660 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
15670 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
15680 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
15690 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
156a0 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
156b0 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
156c0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
156d0 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
156e0 2a 20 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20  * If the action 
156f0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
15700 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
15710 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15720 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
15730 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
15740 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
15750 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
15760 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
15770 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
15780 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
15790 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
157a0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
157b0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
157c0 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
157d0 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
157e0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
157f0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
15800 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
15810 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
15820 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
15830 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
15840 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
15850 74 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 74 68 65  table..** If the
15860 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
15870 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
15880 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
15890 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
158a0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
158b0 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
158c0 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
158d0 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
158e0 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
158f0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
15900 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
15910 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
15920 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
15930 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
15940 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
15950 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
15960 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
15970 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
15980 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
15990 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
159a0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
159b0 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
159c0 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
159d0 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
159e0 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
159f0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
15a00 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
15a10 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
15a20 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
15a30 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
15a40 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
15a50 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
15a60 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
15a70 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
15a80 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
15a90 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
15aa0 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
15ab0 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
15ac0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
15ad0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
15ae0 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
15af0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
15b00 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
15b10 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
15b20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
15b30 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
15b40 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
15b50 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
15b60 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
15b70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
15b80 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
15b90 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
15ba0 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
15bb0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
15bc0 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
15bd0 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
15be0 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
15bf0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
15c00 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
15c10 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
15c20 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
15c30 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
15c40 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
15c50 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
15c60 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
15c70 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
15c80 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
15c90 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
15ca0 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
15cb0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 6c  rizer..**.** Onl
15cc0 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
15cd0 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
15ce0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
15cf0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
15d00 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
15d10 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
15d20 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
15d30 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
15d40 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
15d50 2e 20 20 44 69 73 61 62 6c 65 20 74 68 65 20 61  .  Disable the a
15d60 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
15d70 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
15d80 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
15d90 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
15da0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
15db0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
15dc0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
15dd0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
15de0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
15df0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
15e00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15e10 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
15e20 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
15e30 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
15e40 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
15e50 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
15e60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
15e70 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
15e80 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
15e90 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
15ea0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
15eb0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
15ec0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
15ed0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
15ee0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
15ef0 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
15f00 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
15f10 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
15f20 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
15f30 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
15f40 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
15f50 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
15f60 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
15f70 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
15f80 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
15f90 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
15fa0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15fb0 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
15fc0 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
15fd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
15fe0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
15ff0 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
16000 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
16010 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
16020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
16030 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
16040 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
16050 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
16060 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
16070 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
16080 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
16090 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
160a0 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
160b0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
160c0 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
160d0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
160e0 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
160f0 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
16100 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
16110 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
16120 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2a 0a 2a 2a  ma change..**.**
16130 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
16140 2a 20 5b 48 31 32 35 30 31 5d 20 5b 48 31 32 35  * [H12501] [H125
16150 30 32 5d 20 5b 48 31 32 35 30 33 5d 20 5b 48 31  02] [H12503] [H1
16160 32 35 30 34 5d 20 5b 48 31 32 35 30 35 5d 20 5b  2504] [H12505] [
16170 48 31 32 35 30 36 5d 20 5b 48 31 32 35 30 37 5d  H12506] [H12507]
16180 20 5b 48 31 32 35 31 30 5d 0a 2a 2a 20 5b 48 31   [H12510].** [H1
16190 32 35 31 31 5d 20 5b 48 31 32 35 31 32 5d 20 5b  2511] [H12512] [
161a0 48 31 32 35 32 30 5d 20 5b 48 31 32 35 32 31 5d  H12520] [H12521]
161b0 20 5b 48 31 32 35 32 32 5d 0a 2a 2f 0a 69 6e 74   [H12522].*/.int
161c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
161d0 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
161e0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
161f0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
16200 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
16210 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
16220 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
16230 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
16240 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
16250 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
16260 20 52 65 74 75 72 6e 20 43 6f 64 65 73 20 7b 48   Return Codes {H
16270 31 32 35 39 30 7d 20 3c 48 31 32 35 30 30 3e 0a  12590} <H12500>.
16280 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
16290 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
162a0 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
162b0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
162c0 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
162d0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
162e0 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
162f0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
16300 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
16310 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
16320 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
16330 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
16340 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
16350 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
16360 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
16370 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
16380 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
16390 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
163a0 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  tion..*/.#define
163b0 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
163c0 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
163d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
163e0 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
163f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
16400 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
16410 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
16420 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
16430 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
16440 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16450 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
16460 6e 20 43 6f 64 65 73 20 7b 48 31 32 35 35 30 7d  n Codes {H12550}
16470 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H12500>.**.** 
16480 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
16490 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
164a0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
164b0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
164c0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
164d0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
164e0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
164f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
16500 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
16510 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
16520 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
16530 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
16540 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
16550 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
16560 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
16570 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
16580 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
16590 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
165a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
165b0 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
165c0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
165d0 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
165e0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
165f0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
16600 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
16610 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
16620 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
16630 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
16640 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
16650 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
16660 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
16670 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
16680 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
16690 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
166a0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
166b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
166c0 74 65 72 2e 20 20 54 68 65 20 35 74 68 20 70 61  ter.  The 5th pa
166d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
166e0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
166f0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
16700 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
16710 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
16720 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
16730 70 70 6c 69 63 61 62 6c 65 2e 20 20 54 68 65 20  pplicable.  The 
16740 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
16750 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
16760 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
16770 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
16780 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
16790 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
167a0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
167b0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
167c0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
167d0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
167e0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
167f0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
16800 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
16810 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
16820 73 3a 0a 2a 2a 20 5b 48 31 32 35 35 31 5d 20 5b  s:.** [H12551] [
16830 48 31 32 35 35 32 5d 20 5b 48 31 32 35 35 33 5d  H12552] [H12553]
16840 20 5b 48 31 32 35 35 34 5d 0a 2a 2f 0a 2f 2a 2a   [H12554].*/./**
16850 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16860 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16870 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
16880 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
16890 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
168a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
168b0 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
168c0 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
168d0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
168e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
168f0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
16900 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
16910 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
16920 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
16930 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
16940 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
16950 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
16960 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
16970 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
16980 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16990 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
169a0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
169b0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
169c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
169d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
169e0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
169f0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
16a00 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
16a10 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
16a20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16a30 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
16a40 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
16a50 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
16a60 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16a70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16a80 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
16a90 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
16aa0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
16ab0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
16ac0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
16ad0 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
16ae0 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
16af0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
16b00 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
16b10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16b20 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
16b30 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
16b40 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
16b50 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
16b60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16b70 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
16b80 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
16b90 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
16ba0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
16bb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16bc0 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
16bd0 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
16be0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
16bf0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
16c00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16c10 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
16c20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
16c30 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
16c40 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
16c50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
16c60 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
16c70 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
16c80 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
16c90 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
16ca0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
16cb0 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
16cc0 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
16cd0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
16ce0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
16cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
16d00 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
16d10 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
16d20 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
16d30 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
16d40 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
16d50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
16d60 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
16d70 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
16d80 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
16d90 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
16da0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
16db0 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
16dc0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
16dd0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
16de0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
16df0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
16e00 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
16e10 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
16e20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
16e30 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
16e40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
16e50 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
16e60 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
16e70 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
16e80 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
16e90 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
16ea0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
16eb0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
16ec0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
16ed0 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
16ee0 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
16ef0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
16f00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
16f10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16f20 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
16f30 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
16f40 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
16f50 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16f60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16f70 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
16f80 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
16f90 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
16fa0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
16fb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
16fc0 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
16fd0 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
16fe0 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
16ff0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
17000 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17010 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
17020 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
17030 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
17040 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17050 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17060 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
17070 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
17080 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
17090 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
170a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
170b0 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
170c0 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
170d0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
170e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
170f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17100 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
17110 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
17120 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
17130 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17140 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17150 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
17160 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
17170 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
17180 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
17190 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
171a0 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
171b0 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
171c0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
171d0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
171e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
171f0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
17200 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
17210 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
17220 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
17230 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
17240 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
17250 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
17260 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
17270 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
17280 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
17290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
172a0 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
172b0 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
172c0 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
172d0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
172e0 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 32 32   Functions {H122
172f0 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 20  80} <S60400>.** 
17300 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
17310 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
17320 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
17330 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
17340 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
17350 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
17360 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
17370 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
17380 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
17390 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ** The callback 
173a0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
173b0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
173c0 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
173d0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
173e0 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
173f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
17400 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
17410 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
17420 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   The callback re
17430 74 75 72 6e 73 20 61 20 55 54 46 2d 38 20 72 65  turns a UTF-8 re
17440 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 53  ndering of the S
17450 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
17460 74 0a 2a 2a 20 61 73 20 74 68 65 20 73 74 61 74  t.** as the stat
17470 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
17480 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 20 20 41  ns executing.  A
17490 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c 6c 62 61  dditional callba
174a0 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  cks occur.** as 
174b0 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
174c0 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
174d0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
174e0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
174f0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
17500 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
17510 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
17520 20 74 68 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a   the trigger..**
17530 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
17540 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
17550 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
17560 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
17570 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
17580 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
17590 6e 69 73 68 65 73 2e 20 20 54 68 65 20 70 72 6f  nishes.  The pro
175a0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
175b0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
175c0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
175d0 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
175e0 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
175f0 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
17600 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
17610 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
17620 75 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  un..**.** Requir
17630 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 32  ements:.** [H122
17640 38 31 5d 20 5b 48 31 32 32 38 32 5d 20 5b 48 31  81] [H12282] [H1
17650 32 32 38 33 5d 20 5b 48 31 32 32 38 34 5d 20 5b  2283] [H12284] [
17660 48 31 32 32 38 35 5d 20 5b 48 31 32 32 38 37 5d  H12285] [H12287]
17670 20 5b 48 31 32 32 38 38 5d 20 5b 48 31 32 32 38   [H12288] [H1228
17680 39 5d 0a 2a 2a 20 5b 48 31 32 32 39 30 5d 0a 2a  9].** [H12290].*
17690 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
176a0 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
176b0 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65  te3_trace(sqlite
176c0 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65  3*, void(*xTrace
176d0 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
176e0 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
176f0 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
17700 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  L void *sqlite3_
17710 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
17720 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
17730 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
17740 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
17750 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
17760 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17770 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
17780 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 31  Callbacks {H1291
17790 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a  0} <S60400>.**.*
177a0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
177b0 6f 6e 66 69 67 75 72 65 73 20 61 20 63 61 6c 6c  onfigures a call
177c0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2d 20  back function - 
177d0 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65 73 73 20  the.** progress 
177e0 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68 61 74 20  callback - that 
177f0 69 73 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  is invoked perio
17800 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
17810 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 63  ong.** running c
17820 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
17830 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
17840 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 0a 2a  e3_step()] and.*
17850 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
17860 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20 65 78 61  able()].  An exa
17870 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
17880 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
17890 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
178a0 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
178b0 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
178c0 0a 2a 2a 20 49 66 20 74 68 65 20 70 72 6f 67 72  .** If the progr
178d0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
178e0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
178f0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
17900 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
17910 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
17920 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
17930 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
17940 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
17950 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
17960 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
17970 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
17980 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 64 6f  dler must not do
17990 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
179a0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
179b0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
179c0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
179d0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
179e0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
179f0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
17a00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
17a10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
17a20 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
17a30 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
17a40 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
17a50 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
17a60 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
17a70 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
17a80 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
17a90 2a 20 5b 48 31 32 39 31 31 5d 20 5b 48 31 32 39  * [H12911] [H129
17aa0 31 32 5d 20 5b 48 31 32 39 31 33 5d 20 5b 48 31  12] [H12913] [H1
17ab0 32 39 31 34 5d 20 5b 48 31 32 39 31 35 5d 20 5b  2914] [H12915] [
17ac0 48 31 32 39 31 36 5d 20 5b 48 31 32 39 31 37 5d  H12916] [H12917]
17ad0 20 5b 48 31 32 39 31 38 5d 0a 2a 2a 0a 2a 2f 0a   [H12918].**.*/.
17ae0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
17af0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
17b00 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
17b10 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
17b20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17b30 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
17b40 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
17b50 65 63 74 69 6f 6e 20 7b 48 31 32 37 30 30 7d 20  ection {H12700} 
17b60 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S40200>.**.** T
17b70 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
17b80 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
17b90 61 62 61 73 65 20 66 69 6c 65 20 77 68 6f 73 65  abase file whose
17ba0 20 6e 61 6d 65 20 69 73 20 67 69 76 65 6e 20 62   name is given b
17bb0 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  y the.** filenam
17bc0 65 20 61 72 67 75 6d 65 6e 74 2e 20 54 68 65 20  e argument. The 
17bd0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
17be0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
17bf0 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
17c00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
17c10 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
17c20 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
17c30 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
17c40 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
17c50 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
17c60 31 36 28 29 2e 20 41 20 5b 64 61 74 61 62 61 73  16(). A [databas
17c70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
17c80 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
17c90 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
17ca0 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
17cb0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
17cc0 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
17cd0 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
17ce0 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
17cf0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
17d00 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
17d10 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
17d20 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
17d30 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
17d40 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
17d50 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
17d60 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
17d70 20 6f 62 6a 65 63 74 2e 20 49 66 20 74 68 65 20   object. If the 
17d80 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
17d90 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
17da0 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
17db0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
17dc0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
17dd0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
17de0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
17df0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 0a   returned.  The.
17e00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
17e10 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
17e20 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
17e30 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
17e40 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
17e50 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
17e60 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
17e70 6f 66 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  of the error..**
17e80 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
17e90 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
17ea0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
17eb0 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
17ec0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
17ed0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
17ee0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
17ef0 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
17f00 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
17f10 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
17f20 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
17f30 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
17f40 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
17f50 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
17f60 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
17f70 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
17f80 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
17f90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
17fa0 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
17fb0 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
17fc0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
17fd0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
17fe0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
17ff0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
18000 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
18010 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
18020 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
18030 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
18040 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
18050 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
18060 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
18070 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
18080 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
18090 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
180a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  e connection.  T
180b0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
180c0 65 72 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  er can take one 
180d0 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
180e0 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
180f0 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
18100 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
18110 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
18120 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
18130 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
18140 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
18150 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
18160 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
18170 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
18180 45 5d 20 66 6c 61 67 73 3a 0a 2a 2a 0a 2a 2a 20  E] flags:.**.** 
18190 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  <dl>.** <dt>[SQL
181a0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
181b0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
181c0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
181d0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
181e0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
181f0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
18200 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
18210 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
18220 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a   returned.</dd>.
18230 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54  **.** <dt>[SQLIT
18240 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
18250 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
18260 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
18270 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
18280 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
18290 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
182a0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
182b0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
182c0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
182d0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
182e0 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
182f0 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
18300 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
18310 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
18320 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
18330 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  eturned.</dd>.**
18340 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  .** <dt>[SQLITE_
18350 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
18360 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
18370 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  REATE]</dt>.** <
18380 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
18390 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
183a0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
183b0 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65  g, and is create
183c0 73 20 69 74 20 69 66 0a 2a 2a 20 69 74 20 64 6f  s it if.** it do
183d0 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
183e0 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
183f0 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
18400 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
18410 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
18420 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
18430 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 0a  _open16().</dd>.
18440 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
18450 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
18460 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
18470 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
18480 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
18490 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
184a0 20 61 62 6f 76 65 20 6f 72 20 6f 6e 65 20 6f 66   above or one of
184b0 20 74 68 65 20 63 6f 6d 62 69 6e 61 74 69 6f 6e   the combination
184c0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 63 6f  s shown above co
184d0 6d 62 69 6e 65 64 0a 2a 2a 20 77 69 74 68 20 74  mbined.** with t
184e0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
184f0 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
18500 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
18510 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  ],.** [SQLITE_OP
18520 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
18530 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
18540 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
18550 20 66 6c 61 67 73 2c 0a 2a 2a 20 74 68 65 6e 20   flags,.** then 
18560 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
18570 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
18580 20 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   If the [SQLITE_
18590 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
185a0 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
185b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
185c0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
185d0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
185e0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
185f0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
18600 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
18610 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
18620 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
18630 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
18640 74 61 72 74 2d 74 69 6d 65 2e 20 20 49 66 20 74  tart-time.  If t
18650 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
18660 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
18670 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
18680 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18690 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
186a0 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
186b0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
186c0 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
186d0 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
186e0 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
186f0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
18700 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
18710 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
18720 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
18730 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
18740 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18750 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
18760 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
18770 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
18780 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
18790 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
187a0 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
187b0 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
187c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
187d0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
187e0 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 53 51 4c  )].  The.** [SQL
187f0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
18800 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
18810 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
18820 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f  connection to no
18830 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65  t.** participate
18840 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68   in [shared cach
18850 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20  e mode] even if 
18860 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  it is enabled..*
18870 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65  *.** If the file
18880 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
18890 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
188a0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
188b0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
188c0 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
188d0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
188e0 6e 2e 20 20 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  n.  This in-memo
188f0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
18900 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
18910 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
18920 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
18930 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
18940 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
18950 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
18960 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
18970 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
18980 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
18990 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
189a0 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
189b0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
189c0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
189d0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
189e0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
189f0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
18a00 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
18a10 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
18a20 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
18a30 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
18a40 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
18a50 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ity..**.** If th
18a60 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
18a70 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
18a80 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
18a90 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
18aa0 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
18ab0 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 54  l be created.  T
18ac0 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
18ad0 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
18ae0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
18af0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
18b00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18b10 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
18b20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f  ed..**.** The fo
18b30 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
18b40 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
18b50 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
18b60 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
18b70 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
18b80 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
18b90 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
18ba0 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
18bb0 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
18bc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
18bd0 68 6f 75 6c 64 20 75 73 65 2e 20 20 49 66 20 74  hould use.  If t
18be0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
18bf0 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
18c00 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
18c10 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
18c20 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
18c30 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
18c40 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
18c50 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
18c60 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
18c70 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
18c80 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
18c90 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
18ca0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
18cb0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
18cc0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
18cd0 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
18ce0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
18cf0 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
18d00 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
18d10 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
18d20 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
18d30 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
18d40 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
18d50 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
18d60 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
18d70 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
18d80 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
18d90 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 37 30 31  ents:.** [H12701
18da0 5d 20 5b 48 31 32 37 30 32 5d 20 5b 48 31 32 37  ] [H12702] [H127
18db0 30 33 5d 20 5b 48 31 32 37 30 34 5d 20 5b 48 31  03] [H12704] [H1
18dc0 32 37 30 36 5d 20 5b 48 31 32 37 30 37 5d 20 5b  2706] [H12707] [
18dd0 48 31 32 37 30 39 5d 20 5b 48 31 32 37 31 31 5d  H12709] [H12711]
18de0 0a 2a 2a 20 5b 48 31 32 37 31 32 5d 20 5b 48 31  .** [H12712] [H1
18df0 32 37 31 33 5d 20 5b 48 31 32 37 31 34 5d 20 5b  2713] [H12714] [
18e00 48 31 32 37 31 37 5d 20 5b 48 31 32 37 31 39 5d  H12717] [H12719]
18e10 20 5b 48 31 32 37 32 31 5d 20 5b 48 31 32 37 32   [H12721] [H1272
18e20 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  3].*/.int sqlite
18e30 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
18e40 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
18e50 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
18e60 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
18e70 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
18e80 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
18e90 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
18ea0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
18eb0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
18ec0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
18ed0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
18ee0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
18ef0 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
18f00 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
18f10 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
18f20 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
18f30 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
18f40 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
18f50 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
18f60 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
18f70 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
18f80 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
18f90 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
18fa0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
18fb0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
18fc0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
18fd0 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
18fe0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
18ff0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
19000 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
19010 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
19020 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
19030 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
19040 61 67 65 73 20 7b 48 31 32 38 30 30 7d 20 3c 53  ages {H12800} <S
19050 36 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  60200>.**.** The
19060 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
19070 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
19080 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
19090 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
190a0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
190b0 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
190c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
190d0 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
190e0 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73   API call.** ass
190f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
19100 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19110 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72  ion]. If a prior
19120 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
19130 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74  .** but the most
19140 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
19150 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
19160 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
19170 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72  m.** sqlite3_err
19180 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
19190 6e 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ned.  The sqlite
191a0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
191b0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
191c0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
191d0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
191e0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
191f0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
19200 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
19210 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
19220 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
19230 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
19240 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72  * The sqlite3_er
19250 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
19260 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
19270 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
19280 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
19290 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
192a0 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
192b0 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
192c0 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
192d0 2a 2a 20 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  ** Memory to hol
192e0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
192f0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
19300 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
19310 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
19320 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
19330 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
19340 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
19350 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
19360 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
19370 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
19380 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
19390 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
193a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
193b0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
193c0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
193d0 73 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  s..**.** When th
193e0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
193f0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
19400 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
19410 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
19420 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
19430 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
19440 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
19450 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
19460 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
19470 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
19480 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
19490 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
194a0 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
194b0 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
194c0 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
194d0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
194e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
194f0 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
19500 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
19510 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
19520 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
19530 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
19540 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
19550 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
19560 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
19570 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
19580 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
19590 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
195a0 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
195b0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
195c0 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
195d0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
195e0 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
195f0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
19600 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
19610 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
19620 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
19630 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
19640 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
19650 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
19660 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
19670 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
19680 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
19690 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
196a0 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
196b0 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
196c0 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
196d0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
196e0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
196f0 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ot be set..**.**
19700 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
19710 2a 20 5b 48 31 32 38 30 31 5d 20 5b 48 31 32 38  * [H12801] [H128
19720 30 32 5d 20 5b 48 31 32 38 30 33 5d 20 5b 48 31  02] [H12803] [H1
19730 32 38 30 37 5d 20 5b 48 31 32 38 30 38 5d 20 5b  2807] [H12808] [
19740 48 31 32 38 30 39 5d 0a 2a 2f 0a 69 6e 74 20 73  H12809].*/.int s
19750 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73  qlite3_errcode(s
19760 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74  qlite3 *db);.int
19770 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
19780 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
19790 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68  3 *db);.const ch
197a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
197b0 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f  sg(sqlite3*);.co
197c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
197d0 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
197e0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
197f0 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
19800 6d 65 6e 74 20 4f 62 6a 65 63 74 20 7b 48 31 33  ment Object {H13
19810 30 30 30 7d 20 3c 48 31 33 30 31 30 3e 0a 2a 2a  000} <H13010>.**
19820 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70   KEYWORDS: {prep
19830 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20  ared statement} 
19840 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
19850 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  ents}.**.** An i
19860 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
19870 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
19880 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73  s a single SQL s
19890 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69  tatement..** Thi
198a0 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69  s object is vari
198b0 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61  ously known as a
198c0 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74 65   "prepared state
198d0 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63  ment" or a.** "c
198e0 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74  ompiled SQL stat
198f0 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79  ement" or simply
19900 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74   as a "statement
19910 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  "..**.** The lif
19920 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74  e of a statement
19930 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d   object goes som
19940 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73  ething like this
19950 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
19960 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20  <li> Create the 
19970 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
19980 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
19990 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64  ()] or a related
199a0 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f  .**      functio
199b0 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20  n..** <li> Bind 
199c0 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20  values to [host 
199d0 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e  parameters] usin
199e0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
199f0 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69  nd_*().**      i
19a00 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c  nterfaces..** <l
19a10 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62  i> Run the SQL b
19a20 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
19a30 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f  e3_step()] one o
19a40 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
19a50 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20   <li> Reset the 
19a60 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
19a70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
19a80 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
19a90 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
19aa0 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
19ab0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
19ac0 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
19ad0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
19ae0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
19af0 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
19b00 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f  *.** Refer to do
19b10 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69  cumentation on i
19b20 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64  ndividual method
19b30 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69  s above for addi
19b40 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
19b50 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ation..*/.typede
19b60 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
19b70 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
19b80 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
19b90 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
19ba0 6d 69 74 73 20 7b 48 31 32 37 36 30 7d 20 3c 53  mits {H12760} <S
19bb0 32 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  20600>.**.** Thi
19bc0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
19bd0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
19be0 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
19bf0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
19c00 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
19c10 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
19c20 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
19c30 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
19c40 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
19c50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
19c60 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
19c70 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
19c80 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
19c90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
19ca0 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
19cb0 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
19cc0 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
19cd0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
19ce0 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
19cf0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
19d00 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
19d10 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
19d20 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
19d30 2e 20 20 54 68 65 20 66 75 6e 63 74 69 6f 6e 20  .  The function 
19d40 72 65 74 75 72 6e 73 20 74 68 65 20 6f 6c 64 20  returns the old 
19d50 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  limit..**.** If 
19d60 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
19d70 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
19d80 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
19d90 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 46   unchanged..** F
19da0 6f 72 20 74 68 65 20 6c 69 6d 69 74 20 63 61 74  or the limit cat
19db0 65 67 6f 72 79 20 6f 66 20 53 51 4c 49 54 45 5f  egory of SQLITE_
19dc0 4c 49 4d 49 54 5f 58 59 5a 20 74 68 65 72 65 20  LIMIT_XYZ there 
19dd0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
19de0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
19df0 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 62 79 20 61  und].** set by a
19e00 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 43 20   compile-time C 
19e10 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
19e20 72 6f 20 6e 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69  ro named .** [li
19e30 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
19e40 58 5f 58 59 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20  X_XYZ]..** (The 
19e50 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65  "_LIMIT_" in the
19e60 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64   name is changed
19e70 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 0a 2a 2a   to "_MAX_".).**
19e80 20 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63   Attempts to inc
19e90 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62  rease a limit ab
19ea0 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70  ove its hard upp
19eb0 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20  er bound are.** 
19ec0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
19ed0 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75  ed to the hard u
19ee0 70 70 65 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a  pper limit..**.*
19ef0 2a 20 52 75 6e 20 74 69 6d 65 20 6c 69 6d 69 74  * Run time limit
19f00 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
19f10 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
19f20 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
19f30 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
19f40 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
19f50 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
19f60 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
19f70 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
19f80 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
19f90 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
19fa0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
19fb0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
19fc0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
19fd0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
19fe0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
19ff0 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
1a000 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
1a010 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
1a020 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
1a030 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
1a040 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
1a050 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
1a060 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
1a070 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
1a080 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
1a090 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
1a0a0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
1a0b0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
1a0c0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
1a0d0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
1a0e0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
1a0f0 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
1a100 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
1a110 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
1a120 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
1a130 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
1a140 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
1a150 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1a160 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
1a170 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
1a180 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
1a190 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
1a1a0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
1a1b0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
1a1c0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
1a1d0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
1a1e0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
1a1f0 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
1a200 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
1a210 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
1a220 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
1a230 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
1a240 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  re releases..**.
1a250 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1a260 0a 2a 2a 20 5b 48 31 32 37 36 32 5d 20 5b 48 31  .** [H12762] [H1
1a270 32 37 36 36 5d 20 5b 48 31 32 37 36 39 5d 0a 2a  2766] [H12769].*
1a280 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  /.int sqlite3_li
1a290 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
1a2a0 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
1a2b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a2c0 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
1a2d0 69 74 20 43 61 74 65 67 6f 72 69 65 73 20 7b 48  it Categories {H
1a2e0 31 32 37 39 30 7d 20 3c 48 31 32 37 36 30 3e 0a  12790} <H12760>.
1a2f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
1a300 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 6c  mit category} {l
1a310 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
1a320 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
1a330 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
1a340 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
1a350 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
1a360 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
1a370 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
1a380 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1a390 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
1a3a0 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
1a3b0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
1a3c0 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
1a3d0 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
1a3e0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
1a3f0 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
1a400 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
1a410 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
1a420 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
1a430 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1a440 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1a450 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1a460 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
1a470 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
1a480 62 6c 65 20 72 6f 77 2e 3c 64 64 3e 0a 2a 2a 0a  ble row.<dd>.**.
1a490 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1a4a0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
1a4b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1a4c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1a4d0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1a4e0 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  t.</dd>.**.** <d
1a4f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
1a500 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
1a510 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1a520 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1a530 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
1a540 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
1a550 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
1a560 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
1a570 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1a580 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1a590 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
1a5a0 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
1a5b0 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
1a5c0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
1a5d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
1a5e0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
1a5f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1a600 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
1a610 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
1a620 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
1a630 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1a640 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
1a650 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
1a660 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1a670 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
1a680 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
1a690 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
1a6a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1a6b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1a6c0 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
1a6d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1a6e0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
1a6f0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
1a700 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
1a710 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
1a720 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
1a730 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ement.</dd>.**.*
1a740 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  * <dt>SQLITE_LIM
1a750 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
1a760 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a770 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1a780 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
1a790 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 0a   function.</dd>.
1a7a0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1a7b0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
1a7c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a7d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1a7e0 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
1a7f0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
1a800 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1a810 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
1a820 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
1a830 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1a840 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
1a850 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
1a860 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
1a870 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
1a880 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
1a890 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1a8a0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1a8b0 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
1a8c0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1a8d0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 72 69  m number of vari
1a8e0 61 62 6c 65 73 20 69 6e 20 61 6e 20 53 51 4c 20  ables in an SQL 
1a8f0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 63  statement that c
1a900 61 6e 0a 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c  an.** be bound.<
1a910 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
1a920 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
1a930 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
1a940 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1a950 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
1a960 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
1a970 73 2e 3c 2f 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e  s.</dd>.** </dl>
1a980 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1a990 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
1a9a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1a9b0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
1a9c0 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1a9d0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1a9e0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1a9f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1aa00 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
1aa10 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
1aa20 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1aa30 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1aa40 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
1aa50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1aa60 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
1aa70 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
1aa80 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
1aa90 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
1aaa0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
1aab0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
1aac0 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
1aad0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
1aae0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1aaf0 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
1ab00 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
1ab10 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1ab20 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1ab30 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
1ab40 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1ab50 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1ab60 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
1ab70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1ab80 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1ab90 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
1aba0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1abb0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
1abc0 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 30   Statement {H130
1abd0 31 30 7d 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 20  10} <S10000>.** 
1abe0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
1abf0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
1ac00 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
1ac10 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
1ac20 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
1ac30 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
1ac40 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
1ac50 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
1ac60 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
1ac70 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
1ac80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
1ac90 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
1aca0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1acb0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
1acc0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
1acd0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1ace0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1acf0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1ad00 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1ad10 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
1ad20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ad30 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
1ad40 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
1ad50 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
1ad60 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
1ad70 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
1ad80 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
1ad90 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
1ada0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1adb0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
1adc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1add0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1ade0 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
1adf0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
1ae00 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
1ae10 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
1ae20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1ae30 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
1ae40 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  -16..**.** If th
1ae50 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1ae60 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
1ae70 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
1ae80 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
1ae90 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
1aea0 72 6d 69 6e 61 74 6f 72 2e 20 49 66 20 6e 42 79  rminator. If nBy
1aeb0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1aec0 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
1aed0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
1aee0 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
1aef0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
1af00 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
1af10 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
1af20 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
1af30 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
1af40 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
1af50 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
1af60 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
1af70 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
1af80 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
1af90 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
1afa0 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
1afb0 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
1afc0 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
1afd0 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
1afe0 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
1aff0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
1b000 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
1b010 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
1b020 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
1b030 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
1b040 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
1b050 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
1b060 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
1b070 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
1b080 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
1b090 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a  ator bytes..**.*
1b0a0 2a 20 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e  * If pzTail is n
1b0b0 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a  ot NULL then *pz
1b0c0 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20  Tail is made to 
1b0d0 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72  point to the fir
1b0e0 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20  st byte.** past 
1b0f0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
1b100 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  irst SQL stateme
1b110 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65  nt in zSql.  The
1b120 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79  se routines only
1b130 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20  .** compile the 
1b140 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20  first statement 
1b150 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54  in zSql, so *pzT
1b160 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  ail is left poin
1b170 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20  ting to.** what 
1b180 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c  remains uncompil
1b190 65 64 2e 0a 2a 2a 0a 2a 2a 20 2a 70 70 53 74 6d  ed..**.** *ppStm
1b1a0 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
1b1b0 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
1b1c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1b1d0 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
1b1e0 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
1b1f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
1b200 70 28 29 5d 2e 20 20 49 66 20 74 68 65 72 65 20  p()].  If there 
1b210 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
1b220 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
1b230 6f 20 4e 55 4c 4c 2e 20 20 49 66 20 74 68 65 20  o NULL.  If the 
1b240 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
1b250 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
1b260 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
1b270 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
1b280 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
1b290 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
1b2a0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
1b2b0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
1b2c0 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
1b2d0 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
1b2e0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
1b2f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
1b300 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
1b310 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
1b320 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1b330 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
1b340 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
1b350 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63 63 65  ..**.** On succe
1b360 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  ss, [SQLITE_OK] 
1b370 69 73 20 72 65 74 75 72 6e 65 64 2c 20 6f 74 68  is returned, oth
1b380 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1b390 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1b3a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1b3b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1b3c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1b3d0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
1b3e0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
1b3f0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
1b400 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
1b410 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
1b420 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
1b430 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
1b440 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1b450 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
1b460 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
1b470 61 67 65 64 2e 0a 2a 2a 20 49 6e 20 74 68 65 20  aged..** In the 
1b480 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
1b490 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
1b4a0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
1b4b0 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
1b4c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
1b4d0 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
1b4e0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
1b4f0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
1b500 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
1b510 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1b520 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
1b530 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 61 20 64  to.** behave a d
1b540 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 77  ifferently in tw
1b550 6f 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  o ways:.**.** <o
1b560 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 49 66  l>.** <li>.** If
1b570 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
1b580 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
1b590 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
1b5a0 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
1b5b0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
1b5c0 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
1b5d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b5e0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
1b5f0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
1b600 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
1b610 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
1b620 20 69 74 20 61 67 61 69 6e 2e 20 20 49 66 20 74   it again.  If t
1b630 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63 68  he schema has ch
1b640 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77 61  anged in.** a wa
1b650 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65  y that makes the
1b660 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c 6f   statement no lo
1b670 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71 6c  nger valid, [sql
1b680 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1b690 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  l still.** retur
1b6a0 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
1b6b0 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20 74  ].  But unlike t
1b6c0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1b6d0 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  or, [SQLITE_SCHE
1b6e0 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61 20  MA] is.** now a 
1b6f0 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43 61  fatal error.  Ca
1b700 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  lling [sqlite3_p
1b710 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67 61  repare_v2()] aga
1b720 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b 65  in will not make
1b730 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67 6f   the.** error go
1b740 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75 73   away.  Note: us
1b750 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  e [sqlite3_errms
1b760 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68 65  g()] to find the
1b770 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65 20   text.** of the 
1b780 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74 68  parsing error th
1b790 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61 6e  at results in an
1b7a0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
1b7b0 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c 69   return..** </li
1b7c0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
1b7d0 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63  When an error oc
1b7e0 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73  curs, [sqlite3_s
1b7f0 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  tep()] will retu
1b800 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65  rn one of the de
1b810 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72  tailed.** [error
1b820 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65   codes] or [exte
1b830 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73  nded error codes
1b840 5d 2e 20 20 54 68 65 20 6c 65 67 61 63 79 20 62  ].  The legacy b
1b850 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
1b860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
1b870 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
1b880 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
1b890 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
1b8a0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
1b8b0 6e 64 20 79 6f 75 20 77 6f 75 6c 64 20 68 61 76  nd you would hav
1b8c0 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
1b8d0 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
1b8e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e 20  te3_reset()] in 
1b8f0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 66 69 6e 64  order.** to find
1b900 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
1b910 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
1b920 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
1b930 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
1b940 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
1b950 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
1b960 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
1b970 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
1b980 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
1b990 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ol>.**.** 
1b9a0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
1b9b0 20 5b 48 31 33 30 31 31 5d 20 5b 48 31 33 30 31   [H13011] [H1301
1b9c0 32 5d 20 5b 48 31 33 30 31 33 5d 20 5b 48 31 33  2] [H13013] [H13
1b9d0 30 31 34 5d 20 5b 48 31 33 30 31 35 5d 20 5b 48  014] [H13015] [H
1b9e0 31 33 30 31 36 5d 20 5b 48 31 33 30 31 39 5d 20  13016] [H13019] 
1b9f0 5b 48 31 33 30 32 31 5d 0a 2a 2a 0a 2a 2f 0a 69  [H13021].**.*/.i
1ba00 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1ba10 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
1ba20 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1ba30 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1ba40 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1ba50 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1ba60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1ba70 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1ba80 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1ba90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1baa0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1bab0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1bac0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1bad0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1bae0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1baf0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1bb00 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1bb10 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1bb20 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1bb30 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1bb40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1bb50 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
1bb60 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1bb70 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1bb80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1bb90 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1bba0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1bbb0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1bbc0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1bbd0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1bbe0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1bbf0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1bc00 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1bc10 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1bc20 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1bc30 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1bc40 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1bc50 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1bc60 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1bc70 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1bc80 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1bc90 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
1bca0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1bcb0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1bcc0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1bcd0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
1bce0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1bcf0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
1bd00 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
1bd10 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1bd20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1bd30 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1bd40 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1bd50 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1bd60 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1bd70 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1bd80 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1bd90 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1bda0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1bdb0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1bdc0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1bdd0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1bde0 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
1bdf0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1be00 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1be10 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1be20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
1be30 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1be40 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
1be50 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1be60 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1be70 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1be80 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1be90 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1bea0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1beb0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1bec0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1bed0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
1bee0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1bef0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1bf00 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1bf10 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1bf20 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
1bf30 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
1bf40 20 7b 48 31 33 31 30 30 7d 20 3c 48 31 33 30 30   {H13100} <H1300
1bf50 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  0>.**.** This in
1bf60 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1bf70 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
1bf80 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
1bf90 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
1bfa0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
1bfb0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
1bfc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
1bfd0 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
1bfe0 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
1bff0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
1c000 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1c010 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
1c020 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1c030 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
1c040 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 31 30 31  ents:.** [H13101
1c050 5d 20 5b 48 31 33 31 30 32 5d 20 5b 48 31 33 31  ] [H13102] [H131
1c060 30 33 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  03].*/.const cha
1c070 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
1c080 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
1c090 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
1c0a0 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
1c0b0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
1c0c0 6a 65 63 74 20 7b 48 31 35 30 30 30 7d 20 3c 53  ject {H15000} <S
1c0d0 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  20200>.** KEYWOR
1c0e0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73  DS: {protected s
1c0f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75  qlite3_value} {u
1c100 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
1c110 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20  e3_value}.**.** 
1c120 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
1c130 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1c140 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e  ject to represen
1c150 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20  t all values.** 
1c160 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72  that can be stor
1c170 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65  ed in a database
1c180 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75   table. SQLite u
1c190 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69  ses dynamic typi
1c1a0 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61  ng.** for the va
1c1b0 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20  lues it stores. 
1c1c0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
1c1d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1c1e0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
1c1f0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
1c200 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
1c210 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
1c220 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
1c230 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
1c240 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
1c250 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
1c260 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
1c270 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
1c280 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
1c290 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
1c2a0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
1c2b0 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
1c2c0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
1c2d0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
1c2e0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
1c2f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
1c300 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
1c310 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
1c320 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
1c330 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
1c340 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
1c350 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
1c360 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
1c370 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
1c380 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
1c390 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
1c3a0 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
1c3b0 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
1c3c0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
1c3d0 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c  eld.  A internal
1c3e0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1c3f0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
1c400 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1c410 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
1c420 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1c430 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
1c440 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
1c450 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
1c460 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
1c470 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
1c480 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
1c490 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c4a0 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
1c4b0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
1c4c0 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
1c4d0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
1c4e0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
1c4f0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
1c500 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
1c510 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
1c520 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
1c530 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
1c540 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
1c550 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
1c560 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
1c570 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
1c580 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
1c590 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1c5a0 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
1c5b0 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
1c5c0 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
1c5d0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
1c5e0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
1c5f0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
1c600 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
1c610 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
1c620 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
1c630 6f 6e 20 62 65 74 77 65 65 6e 20 62 65 74 77 65  on between betwe
1c640 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
1c650 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1c660 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1c670 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
1c680 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
1c690 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
1c6a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1c6b0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
1c6c0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
1c6d0 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
1c6e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1c6f0 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
1c700 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
1c710 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
1c720 63 74 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c  cted..** The sql
1c730 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1c740 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
1c750 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1c760 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
1c770 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
1c780 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1c790 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
1c7a0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
1c7b0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
1c7c0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
1c7d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
1c7e0 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
1c7f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
1c800 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
1c810 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
1c820 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
1c830 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
1c840 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1c850 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
1c860 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1c870 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
1c880 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
1c890 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
1c8a0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
1c8b0 63 74 20 7b 48 31 36 30 30 31 7d 20 3c 53 32 30  ct {H16001} <S20
1c8c0 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  200>.**.** The c
1c8d0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
1c8e0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
1c8f0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
1c900 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
1c910 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
1c920 63 74 2e 20 20 41 20 70 6f 69 6e 74 65 72 20 74  ct.  A pointer t
1c930 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
1c940 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
1c950 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
1c960 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
1c970 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
1c980 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
1c990 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1c9a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1c9b0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
1c9c0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
1c9d0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
1c9e0 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
1c9f0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1ca00 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
1ca10 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
1ca20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
1ca30 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
1ca40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
1ca50 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
1ca60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
1ca70 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
1ca80 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
1ca90 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
1caa0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
1cab0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
1cac0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1cad0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
1cae0 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
1caf0 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
1cb00 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
1cb10 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
1cb20 73 20 7b 48 31 33 35 30 30 7d 20 3c 53 37 30 33  s {H13500} <S703
1cb30 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  00>.** KEYWORDS:
1cb40 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1cb50 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
1cb60 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
1cb70 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
1cb80 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
1cb90 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
1cba0 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
1cbb0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
1cbc0 2a 20 49 6e 20 74 68 65 20 53 51 4c 20 73 74 72  * In the SQL str
1cbd0 69 6e 67 73 20 69 6e 70 75 74 20 74 6f 20 5b 73  ings input to [s
1cbe0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1cbf0 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
1cc00 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
1cc10 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
1cc20 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
1cc30 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
1cc40 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
1cc50 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
1cc60 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
1cc70 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
1cc80 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
1cc90 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
1cca0 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
1ccb0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
1ccc0 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
1ccd0 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
1cce0 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
1ccf0 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
1cd00 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
1cd10 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
1cd20 65 6e 74 69 66 65 72 2e 20 20 54 68 65 20 76 61  entifer.  The va
1cd30 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
1cd40 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
1cd50 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
1cd60 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
1cd70 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
1cd80 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
1cd90 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
1cda0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
1cdb0 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
1cdc0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ere..**.** The f
1cdd0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
1cde0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1cdf0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
1ce00 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
1ce10 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1ce20 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
1ce30 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
1ce40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1ce50 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
1ce60 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
1ce70 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
1ce80 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
1ce90 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
1cea0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
1ceb0 74 2e 0a 2a 2a 20 54 68 65 20 6c 65 66 74 6d 6f  t..** The leftmo
1cec0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
1ced0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
1cee0 20 31 2e 20 20 57 68 65 6e 20 74 68 65 20 73 61   1.  When the sa
1cef0 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
1cf00 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
1cf10 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
1cf20 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
1cf30 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
1cf40 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
1cf50 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
1cf60 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
1cf70 63 65 2e 0a 2a 2a 20 54 68 65 20 69 6e 64 65 78  ce..** The index
1cf80 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
1cf90 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
1cfa0 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
1cfb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1cfc0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1cfd0 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
1cfe0 72 65 64 2e 20 20 54 68 65 20 69 6e 64 65 78 0a  red.  The index.
1cff0 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
1d000 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
1d010 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
1d020 20 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d   The NNN value m
1d030 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
1d040 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
1d050 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
1d060 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
1d070 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
1d080 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
1d090 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
1d0a0 2a 2a 20 54 68 65 20 74 68 69 72 64 20 61 72 67  ** The third arg
1d0b0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
1d0c0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
1d0d0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
1d0e0 2a 2a 20 49 6e 20 74 68 6f 73 65 20 72 6f 75 74  ** In those rout
1d0f0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
1d100 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
1d110 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
1d120 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1d130 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
1d140 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
1d150 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
1d160 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
1d170 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
1d180 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
1d190 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
1d1a0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
1d1b0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
1d1c0 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74  rameter is negat
1d1d0 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20  ive, the length 
1d1e0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
1d1f0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1d200 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
1d210 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
1d220 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54  minator..**.** T
1d230 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1d240 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
1d250 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
1d260 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
1d270 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
1d280 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
1d290 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
1d2a0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
1d2b0 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
1d2c0 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
1d2d0 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
1d2e0 69 74 68 20 69 74 2e 20 49 66 20 74 68 65 20 66  ith it. If the f
1d2f0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
1d300 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
1d310 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
1d320 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
1d330 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
1d340 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
1d350 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
1d360 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
1d370 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
1d380 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
1d390 2a 2a 20 49 66 20 74 68 65 20 66 69 66 74 68 20  ** If the fifth 
1d3a0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65  argument has the
1d3b0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54   value [SQLITE_T
1d3c0 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a  RANSIENT], then.
1d3d0 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
1d3e0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
1d3f0 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61  copy of the data
1d400 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
1d410 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69  fore.** the sqli
1d420 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
1d430 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  tine returns..**
1d440 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1d450 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
1d460 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
1d470 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
1d480 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
1d490 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
1d4a0 20 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73   A zeroblob uses
1d4b0 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
1d4c0 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
1d4d0 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
1d4e0 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
1d4f0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
1d500 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
1d510 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
1d520 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
1d530 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
1d540 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
1d550 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
1d560 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
1d570 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
1d580 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
1d590 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
1d5a0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 41 20 6e  routines..** A n
1d5b0 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
1d5c0 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
1d5d0 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
1d5e0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
1d5f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1d600 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1d610 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
1d620 20 61 66 74 65 72 0a 2a 2a 20 5b 73 71 6c 69 74   after.** [sqlit
1d630 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1d640 20 28 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e   (and its varian
1d650 74 73 29 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ts) or [sqlite3_
1d660 72 65 73 65 74 28 29 5d 20 61 6e 64 0a 2a 2a 20  reset()] and.** 
1d670 62 65 66 6f 72 65 20 5b 73 71 6c 69 74 65 33 5f  before [sqlite3_
1d680 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 42 69 6e 64  step()]..** Bind
1d690 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
1d6a0 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
1d6b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
1d6c0 75 74 69 6e 65 2e 0a 2a 2a 20 55 6e 62 6f 75 6e  utine..** Unboun
1d6d0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
1d6e0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1d6f0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  NULL..**.** Thes
1d700 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1d710 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
1d720 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 20 65   success or an e
1d730 72 72 6f 72 20 63 6f 64 65 20 69 66 0a 2a 2a 20  rror code if.** 
1d740 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
1d750 6f 6e 67 2e 20 20 5b 53 51 4c 49 54 45 5f 52 41  ong.  [SQLITE_RA
1d760 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
1d770 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1d780 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
1d790 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5b 53 51  t of range.  [SQ
1d7a0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
1d7b0 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
1d7c0 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5b 53  c() fails..** [S
1d7d0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 69  QLITE_MISUSE] mi
1d7e0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
1d7f0 69 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  if these routine
1d800 73 20 61 72 65 20 63 61 6c 6c 65 64 20 6f 6e 20  s are called on 
1d810 61 0a 2a 2a 20 76 69 72 74 75 61 6c 20 6d 61 63  a.** virtual mac
1d820 68 69 6e 65 20 74 68 61 74 20 69 73 20 74 68 65  hine that is the
1d830 20 77 72 6f 6e 67 20 73 74 61 74 65 20 6f 72 20   wrong state or 
1d840 77 68 69 63 68 20 68 61 73 20 61 6c 72 65 61 64  which has alread
1d850 79 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  y been finalized
1d860 2e 0a 2a 2a 20 44 65 74 65 63 74 69 6f 6e 20 6f  ..** Detection o
1d870 66 20 6d 69 73 75 73 65 20 69 73 20 75 6e 72 65  f misuse is unre
1d880 6c 69 61 62 6c 65 2e 20 20 41 70 70 6c 69 63 61  liable.  Applica
1d890 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
1d8a0 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 53 51   depend.** on SQ
1d8b0 4c 49 54 45 5f 4d 49 53 55 53 45 20 72 65 74 75  LITE_MISUSE retu
1d8c0 72 6e 73 2e 20 20 53 51 4c 49 54 45 5f 4d 49 53  rns.  SQLITE_MIS
1d8d0 55 53 45 20 69 73 20 69 6e 74 65 6e 64 65 64 20  USE is intended 
1d8e0 74 6f 20 69 6e 64 69 63 61 74 65 20 61 0a 2a 2a  to indicate a.**
1d8f0 20 61 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69   a logic error i
1d900 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  n the applicatio
1d910 6e 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  n.  Future versi
1d920 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
1d930 67 68 74 0a 2a 2a 20 70 61 6e 69 63 20 72 61 74  ght.** panic rat
1d940 68 65 72 20 74 68 61 6e 20 72 65 74 75 72 6e 20  her than return 
1d950 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
1d960 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1d970 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1d980 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
1d990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1d9a0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1d9b0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1d9c0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1d9d0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
1d9e0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1d9f0 2a 20 5b 48 31 33 35 30 36 5d 20 5b 48 31 33 35  * [H13506] [H135
1da00 30 39 5d 20 5b 48 31 33 35 31 32 5d 20 5b 48 31  09] [H13512] [H1
1da10 33 35 31 35 5d 20 5b 48 31 33 35 31 38 5d 20 5b  3515] [H13518] [
1da20 48 31 33 35 32 31 5d 20 5b 48 31 33 35 32 34 5d  H13521] [H13524]
1da30 20 5b 48 31 33 35 32 37 5d 0a 2a 2a 20 5b 48 31   [H13527].** [H1
1da40 33 35 33 30 5d 20 5b 48 31 33 35 33 33 5d 20 5b  3530] [H13533] [
1da50 48 31 33 35 33 36 5d 20 5b 48 31 33 35 33 39 5d  H13536] [H13539]
1da60 20 5b 48 31 33 35 34 32 5d 20 5b 48 31 33 35 34   [H13542] [H1354
1da70 35 5d 20 5b 48 31 33 35 34 38 5d 20 5b 48 31 33  5] [H13548] [H13
1da80 35 35 31 5d 0a 2a 2a 0a 2a 2f 0a 69 6e 74 20 73  551].**.*/.int s
1da90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1daa0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1dab0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
1dac0 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29  , int n, void(*)
1dad0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
1dae0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
1daf0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1db00 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69   int, double);.i
1db10 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1db20 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
1db30 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e  *, int, int);.in
1db40 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
1db50 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
1db60 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
1db70 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c  _int64);.int sql
1db80 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73  ite3_bind_null(s
1db90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1dba0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
1dbb0 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
1dbc0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1dbd0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
1dbe0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1dbf0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1dc00 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
1dc10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
1dc20 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
1dc30 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
1dc40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1dc50 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
1dc60 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
1dc70 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
1dc80 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
1dc90 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  bind_zeroblob(sq
1dca0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1dcb0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
1dcc0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
1dcd0 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
1dce0 65 72 73 20 7b 48 31 33 36 30 30 7d 20 3c 53 37  ers {H13600} <S7
1dcf0 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  0300>.**.** This
1dd00 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
1dd10 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
1dd20 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
1dd30 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
1dd40 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
1dd50 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
1dd60 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
1dd70 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
1dd80 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
1dd90 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
1dda0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
1ddb0 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
1ddc0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
1ddd0 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
1dde0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
1ddf0 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
1de00 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
1de10 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
1de20 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
1de30 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
1de40 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
1de50 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
1de60 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
1de70 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
1de80 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
1de90 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
1dea0 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
1deb0 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
1dec0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
1ded0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
1dee0 68 65 20 3f 4e 4e 4e 20 61 72 65 20 75 73 65 64  he ?NNN are used
1def0 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
1df00 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
1df10 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  st..**.** See al
1df20 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
1df30 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
1df40 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
1df50 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1df60 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
1df70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1df80 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1df90 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
1dfa0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1dfb0 36 30 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  601].*/.int sqli
1dfc0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1dfd0 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
1dfe0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
1dff0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
1e000 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
1e010 65 72 20 7b 48 31 33 36 32 30 7d 20 3c 53 37 30  er {H13620} <S70
1e020 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  300>.**.** This 
1e030 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1e040 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1e050 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6e 2d 74   name of the n-t
1e060 68 0a 2a 2a 20 5b 53 51 4c 20 70 61 72 61 6d 65  h.** [SQL parame
1e070 74 65 72 5d 20 69 6e 20 61 20 5b 70 72 65 70 61  ter] in a [prepa
1e080 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1e090 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
1e0a0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
1e0b0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
1e0c0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
1e0d0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
1e0e0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
1e0f0 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
1e100 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
1e110 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
1e120 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
1e130 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
1e140 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
1e150 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
1e160 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
1e170 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
1e180 65 20 6e 61 6d 65 2e 0a 2a 2a 20 50 61 72 61 6d  e name..** Param
1e190 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
1e1a0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
1e1b0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
1e1c0 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
1e1d0 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72  * and are also r
1e1e0 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 61  eferred to as "a
1e1f0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
1e200 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ers"..**.** The 
1e210 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
1e220 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
1e230 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
1e240 2a 0a 2a 2a 20 49 66 20 74 68 65 20 76 61 6c 75  *.** If the valu
1e250 65 20 6e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e n is out of ra
1e260 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 6e 2d  nge or if the n-
1e270 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
1e280 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
1e290 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
1e2a0 65 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 65  ed.  The returne
1e2b0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
1e2c0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
1e2d0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
1e2e0 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
1e2f0 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
1e300 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
1e310 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
1e320 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1e330 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1e340 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1e350 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
1e360 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
1e370 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
1e380 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
1e390 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1e3a0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
1e3b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1e3c0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1e3d0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
1e3e0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33  rements:.** [H13
1e3f0 36 32 31 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  621].*/.const ch
1e400 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
1e410 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
1e420 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1e430 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
1e440 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
1e450 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
1e460 41 20 47 69 76 65 6e 20 4e 61 6d 65 20 7b 48 31  A Given Name {H1
1e470 33 36 34 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a  3640} <S70300>.*
1e480 2a 0a 2a 2a 20 52 65 74 75 72 6e 20 74 68 65 20  *.** Return the 
1e490 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
1e4a0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
1e4b0 69 74 73 20 6e 61 6d 65 2e 20 20 54 68 65 0a 2a  its name.  The.*
1e4c0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
1e4d0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
1e4e0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
1e4f0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
1e500 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
1e510 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1e520 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 41 20  te3_bind()].  A 
1e530 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
1e540 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
1e550 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
1e560 66 6f 75 6e 64 2e 20 20 54 68 65 20 70 61 72 61  found.  The para
1e570 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
1e580 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
1e590 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
1e5a0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1e5b0 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
1e5c0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
1e5d0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
1e5e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1e5f0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
1e600 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1e610 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1e620 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
1e630 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1e640 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
1e650 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
1e660 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
1e670 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  ex()]..**.** Req
1e680 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
1e690 31 33 36 34 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71  13641].*/.int sq
1e6a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1e6b0 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
1e6c0 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
1e6d0 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
1e6e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1e6f0 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
1e700 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
1e710 53 74 61 74 65 6d 65 6e 74 20 7b 48 31 33 36 36  Statement {H1366
1e720 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
1e730 2a 20 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68  * Contrary to th
1e740 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
1e750 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
1e760 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
1e770 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
1e780 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
1e790 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
1e7a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1e7b0 6d 65 6e 74 5d 2e 0a 2a 2a 20 55 73 65 20 74 68  ment]..** Use th
1e7c0 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65  is routine to re
1e7d0 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72  set all host par
1e7e0 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e  ameters to NULL.
1e7f0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1e800 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 36 36 31 5d  nts:.** [H13661]
1e810 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1e820 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
1e830 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
1e840 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e850 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
1e860 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
1e870 74 20 7b 48 31 33 37 31 30 7d 20 3c 53 31 30 37  t {H13710} <S107
1e880 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e  00>.**.** Return
1e890 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1e8a0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
1e8b0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
1e8c0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
1e8d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e8e0 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  . This routine r
1e8f0 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
1e900 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
1e910 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
1e920 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
1e930 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
1e940 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
1e950 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
1e960 3a 0a 2a 2a 20 5b 48 31 33 37 31 31 5d 0a 2a 2f  :.** [H13711].*/
1e970 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
1e980 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
1e990 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
1e9a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e9b0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
1e9c0 20 41 20 52 65 73 75 6c 74 20 53 65 74 20 7b 48   A Result Set {H
1e9d0 31 33 37 32 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13720} <S10700>.
1e9e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1e9f0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
1ea00 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
1ea10 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
1ea20 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
1ea30 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
1ea40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1ea50 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1ea60 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
1ea70 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1ea80 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1ea90 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1eaa0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
1eab0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
1eac0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
1ead0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1eae0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
1eaf0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
1eb00 74 72 69 6e 67 2e 20 20 54 68 65 20 66 69 72 73  tring.  The firs
1eb10 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
1eb20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
1eb30 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
1eb40 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
1eb50 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1eb60 74 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  t. The second pa
1eb70 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
1eb80 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
1eb90 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63    The leftmost c
1eba0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
1ebb0 30 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 74  0..**.** The ret
1ebc0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
1ebd0 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
1ebe0 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
1ebf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ec00 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
1ec10 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
1ec20 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
1ec30 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
1ec40 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
1ec50 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
1ec60 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
1ec70 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
1ec80 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
1ec90 0a 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 6d  .** If sqlite3_m
1eca0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75  alloc() fails du
1ecb0 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73  ring the process
1ecc0 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f  ing of either ro
1ecd0 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78  utine.** (for ex
1ece0 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63  ample during a c
1ecf0 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55  onversion from U
1ed00 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20  TF-8 to UTF-16) 
1ed10 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  then a.** NULL p
1ed20 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
1ed30 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  ed..**.** The na
1ed40 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
1ed50 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
1ed60 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
1ed70 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
1ed80 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
1ed90 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
1eda0 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
1edb0 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
1edc0 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
1edd0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
1ede0 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
1edf0 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
1ee00 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
1ee10 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
1ee20 6e 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  next..**.** Requ
1ee30 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1ee40 33 37 32 31 5d 20 5b 48 31 33 37 32 33 5d 20 5b  3721] [H13723] [
1ee50 48 31 33 37 32 34 5d 20 5b 48 31 33 37 32 35 5d  H13724] [H13725]
1ee60 20 5b 48 31 33 37 32 36 5d 20 5b 48 31 33 37 32   [H13726] [H1372
1ee70 37 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  7].*/.const char
1ee80 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1ee90 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1eea0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
1eeb0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
1eec0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
1eed0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1eee0 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
1eef0 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
1ef00 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
1ef10 20 52 65 73 75 6c 74 20 7b 48 31 33 37 34 30 7d   Result {H13740}
1ef20 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
1ef30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
1ef40 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
1ef50 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 61 74  o determine what
1ef60 20 63 6f 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a   column of what.
1ef70 2a 2a 20 74 61 62 6c 65 20 69 6e 20 77 68 69 63  ** table in whic
1ef80 68 20 64 61 74 61 62 61 73 65 20 61 20 72 65 73  h database a res
1ef90 75 6c 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  ult of a [SELECT
1efa0 5d 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65  ] statement come
1efb0 73 20 66 72 6f 6d 2e 0a 2a 2a 20 54 68 65 20 6e  s from..** The n
1efc0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1efd0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
1efe0 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
1eff0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
1f000 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
1f010 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54  TF-16 string.  T
1f020 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
1f030 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
1f040 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
1f050 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
1f060 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1f070 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
1f080 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
1f090 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
1f0a0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
1f0b0 6d 65 2e 0a 2a 2a 20 54 68 65 20 72 65 74 75 72  me..** The retur
1f0c0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
1f0d0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
1f0e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1f0f0 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
1f100 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
1f110 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
1f120 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
1f130 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
1f140 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
1f150 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
1f160 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
1f170 20 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72   The names retur
1f180 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
1f190 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
1f1a0 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
1f1b0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
1f1c0 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
1f1d0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
1f1e0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 66 6f 6c  ument to the fol
1f1f0 6c 6f 77 69 6e 67 20 63 61 6c 6c 73 20 69 73 20  lowing calls is 
1f200 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
1f210 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 54 68 65 73 65  ement]..** These
1f220 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
1f230 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
1f240 6f 75 74 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  out the Nth colu
1f250 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
1f260 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
1f270 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1f280 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
1f290 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
1f2a0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
1f2b0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
1f2c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
1f2d0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
1f2e0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
1f2f0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
1f300 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
1f310 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
1f320 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
1f330 4c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  L.  These routin
1f340 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
1f350 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
1f360 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f370 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
1f380 20 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65    Otherwise, the
1f390 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
1f3a0 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
1f3b0 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
1f3c0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  e.** and column 
1f3d0 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
1f3e0 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
1f3f0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
1f400 2a 2a 20 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  ** As with all o
1f410 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
1f420 2c 20 74 68 6f 73 65 20 70 6f 73 74 66 69 78 65  , those postfixe
1f430 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
1f440 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
1f450 6f 64 65 64 20 73 74 72 69 6e 67 73 2c 20 74 68  oded strings, th
1f460 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
1f470 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 20  s return UTF-8. 
1f480 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  {END}.**.** Thes
1f490 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
1f4a0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
1f4b0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
1f4c0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
1f4d0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
1f4e0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
1f4f0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
1f500 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
1f510 0a 2a 2a 0a 2a 2a 20 7b 41 31 33 37 35 31 7d 0a  .**.** {A13751}.
1f520 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
1f530 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
1f540 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
1f550 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
1f560 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
1f570 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1f580 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
1f590 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
1f5a0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
1f5b0 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
1f5c0 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  d..**.** Require
1f5d0 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 34  ments:.** [H1374
1f5e0 31 5d 20 5b 48 31 33 37 34 32 5d 20 5b 48 31 33  1] [H13742] [H13
1f5f0 37 34 33 5d 20 5b 48 31 33 37 34 34 5d 20 5b 48  743] [H13744] [H
1f600 31 33 37 34 35 5d 20 5b 48 31 33 37 34 36 5d 20  13745] [H13746] 
1f610 5b 48 31 33 37 34 38 5d 0a 2a 2a 0a 2a 2a 20 49  [H13748].**.** I
1f620 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
1f630 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
1f640 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
1f650 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
1f660 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
1f670 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
1f680 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
1f690 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
1f6a0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
1f6b0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
1f6c0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
1f6d0 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
1f6e0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
1f6f0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1f700 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
1f710 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
1f720 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1f730 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1f740 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
1f750 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
1f760 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1f770 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1f780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
1f790 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1f7a0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
1f7b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
1f7c0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
1f7d0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1f7e0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
1f7f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1f800 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
1f810 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
1f820 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
1f830 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
1f840 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
1f850 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
1f860 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1f870 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
1f880 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
1f890 6c 74 20 7b 48 31 33 37 36 30 7d 20 3c 53 31 30  lt {H13760} <S10
1f8a0 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  700>.**.** The f
1f8b0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
1f8c0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
1f8d0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
1f8e0 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
1f8f0 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
1f900 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
1f910 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
1f920 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
1f930 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
1f940 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
1f950 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
1f960 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
1f970 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
1f980 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
1f990 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
1f9a0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
1f9b0 65 74 75 72 6e 65 64 2e 20 20 49 66 20 74 68 65  eturned.  If the
1f9c0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
1f9d0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
1f9e0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
1f9f0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
1fa00 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
1fa10 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
1fa20 2a 2a 20 54 68 65 20 72 65 74 75 72 6e 65 64 20  ** The returned 
1fa30 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
1fa40 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 20   UTF-8 encoded. 
1fa50 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  {END}.**.** For 
1fa60 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
1fa70 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
1fa80 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
1fa90 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
1faa0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
1fab0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
1fac0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
1fad0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
1fae0 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
1faf0 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
1fb00 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
1fb10 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
1fb20 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
1fb30 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
1fb40 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
1fb50 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
1fb60 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
1fb70 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
1fb80 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 0a 2a 2a  olumn (i==0)..**
1fb90 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
1fba0 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
1fbb0 20 74 79 70 69 6e 67 2e 20 20 53 6f 20 6a 75 73   typing.  So jus
1fbc0 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
1fbd0 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
1fbe0 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
1fbf0 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
1fc00 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
1fc10 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
1fc20 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
1fc30 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
1fc40 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
1fc50 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
1fc60 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
1fc70 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
1fc80 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
1fc90 20 20 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73    Type.** is ass
1fca0 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
1fcb0 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
1fcc0 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
1fcd0 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
1fce0 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
1fcf0 6c 75 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  lues..**.** Requ
1fd00 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
1fd10 33 37 36 31 5d 20 5b 48 31 33 37 36 32 5d 20 5b  3761] [H13762] [
1fd20 48 31 33 37 36 33 5d 0a 2a 2f 0a 63 6f 6e 73 74  H13763].*/.const
1fd30 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
1fd40 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
1fd50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1fd60 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1fd70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
1fd80 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
1fd90 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
1fda0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
1fdb0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
1fdc0 61 74 65 6d 65 6e 74 20 7b 48 31 33 32 30 30 7d  atement {H13200}
1fdd0 20 3c 53 31 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10000>.**.** 
1fde0 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
1fdf0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
1fe00 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
1fe10 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
1fe20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fe30 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
1fe40 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1fe50 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
1fe60 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
1fe70 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
1fe80 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
1fe90 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1fea0 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
1feb0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
1fec0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
1fed0 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
1fee0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
1fef0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
1ff00 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
1ff10 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
1ff20 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
1ff30 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
1ff40 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
1ff50 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
1ff60 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
1ff70 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
1ff80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1ff90 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1ffa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ffb0 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
1ffc0 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
1ffd0 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
1ffe0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
1fff0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20000 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
20010 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
20020 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
20030 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
20040 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
20050 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
20060 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
20070 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
20080 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
20090 2a 2a 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  ** In the legacy
200a0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
200b0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
200c0 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
200d0 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53  ITE_BUSY],.** [S
200e0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
200f0 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
20100 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
20110 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
20120 2a 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  * With the "v2" 
20130 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
20140 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
20150 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
20160 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
20170 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
20180 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
20190 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ll..**.** [SQLIT
201a0 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
201b0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
201c0 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
201d0 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
201e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
201f0 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
20200 6f 20 69 74 73 20 6a 6f 62 2e 20 20 49 66 20 74  o its job.  If t
20210 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
20220 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
20230 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
20240 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
20250 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
20260 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
20270 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
20280 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
20290 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
202a0 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
202b0 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c  within a.** expl
202c0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
202d0 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
202e0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
202f0 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
20300 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
20310 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  **.** [SQLITE_DO
20320 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
20330 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
20340 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
20350 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
20360 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
20370 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
20380 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
20390 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
203a0 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
203b0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
203c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
203d0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
203e0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
203f0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
20400 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
20410 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
20420 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65  tatement being e
20430 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20  xecuted returns 
20440 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b  any data, then [
20450 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69  SQLITE_ROW].** i
20460 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20  s returned each 
20470 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f  time a new row o
20480 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20  f data is ready 
20490 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62  for processing b
204a0 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e  y the.** caller.
204b0 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20   The values may 
204c0 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e  be accessed usin
204d0 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63  g the [column ac
204e0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e  cess functions].
204f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
20500 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61  () is called aga
20510 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74  in to retrieve t
20520 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64  he next row of d
20530 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  ata..**.** [SQLI
20540 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
20550 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
20560 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
20570 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
20580 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
20590 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
205a0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
205b0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
205c0 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
205d0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
205e0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
205f0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
20600 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
20610 20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79   With the legacy
20620 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
20630 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
20640 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
20650 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
20660 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
20670 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
20680 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
20690 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
206a0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
206b0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
206c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
206d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
206e0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 6e   statement].  In
206f0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
20700 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
20710 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
20720 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
20730 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
20740 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
20750 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
20760 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
20770 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
20780 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
20790 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
207a0 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
207b0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
207c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
207d0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
207e0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
207f0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
20800 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
20810 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
20820 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
20830 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
20840 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
20850 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
20860 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
20870 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
20880 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
20890 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
208a0 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
208b0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
208c0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
208d0 65 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  e..**.** <b>Goof
208e0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
208f0 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
20900 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
20910 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
20920 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
20930 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
20940 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
20950 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
20960 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
20970 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
20980 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
20990 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
209a0 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
209b0 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
209c0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
209d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
209e0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
209f0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
20a00 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
20a10 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
20a20 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
20a30 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
20a40 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
20a50 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
20a60 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
20a70 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
20a80 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
20a90 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
20aa0 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
20ab0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
20ac0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
20ad0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
20ae0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
20af0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
20b00 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
20b10 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
20b20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
20b30 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
20b40 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
20b50 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
20b60 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
20b70 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
20b80 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
20b90 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
20ba0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
20bb0 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
20bc0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
20bd0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
20be0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
20bf0 2a 2a 20 5b 48 31 33 32 30 32 5d 20 5b 48 31 35  ** [H13202] [H15
20c00 33 30 34 5d 20 5b 48 31 35 33 30 36 5d 20 5b 48  304] [H15306] [H
20c10 31 35 33 30 38 5d 20 5b 48 31 35 33 31 30 5d 0a  15308] [H15310].
20c20 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
20c30 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
20c40 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
20c50 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
20c60 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
20c70 6c 74 20 73 65 74 20 7b 48 31 33 37 37 30 7d 20  lt set {H13770} 
20c80 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 52  <S10700>.**.** R
20c90 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
20ca0 72 20 6f 66 20 76 61 6c 75 65 73 20 69 6e 20 74  r of values in t
20cb0 68 65 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  he current row o
20cc0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
20cd0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
20ce0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37 37 31  ents:.** [H13771
20cf0 5d 20 5b 48 31 33 37 37 32 5d 0a 2a 2f 0a 69 6e  ] [H13772].*/.in
20d00 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
20d10 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
20d20 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
20d30 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
20d40 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
20d50 73 20 7b 48 31 30 32 36 35 7d 20 3c 53 31 30 31  s {H10265} <S101
20d60 31 30 3e 3c 53 31 30 31 32 30 3e 0a 2a 2a 20 4b  10><S10120>.** K
20d70 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
20d80 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b 48 31 30 32  TEXT.**.** {H102
20d90 36 36 7d 20 45 76 65 72 79 20 76 61 6c 75 65 20  66} Every value 
20da0 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
20db0 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
20dc0 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
20dd0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
20de0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
20df0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
20e00 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
20e10 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
20e20 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
20e30 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
20e40 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
20e50 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  </ul> {END}.**.*
20e60 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
20e70 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
20e80 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
20e90 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
20ea0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
20eb0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
20ec0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
20ed0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
20ee0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
20ef0 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
20f00 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
20f10 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
20f20 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
20f30 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
20f40 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
20f50 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
20f60 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
20f70 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
20f80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20f90 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
20fa0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
20fb0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
20fc0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
20fd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
20fe0 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
20ff0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
21000 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
21010 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
21020 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
21030 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
21040 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
21050 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
21060 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
21070 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 20  es From A Query 
21080 7b 48 31 33 38 30 30 7d 20 3c 53 31 30 37 30 30  {H13800} <S10700
21090 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
210a0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
210b0 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54  nctions}.**.** T
210c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hese routines fo
210d0 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73  rm the "result s
210e0 65 74 20 71 75 65 72 79 22 20 69 6e 74 65 72 66  et query" interf
210f0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ace..**.** These
21100 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
21110 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
21120 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
21130 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
21140 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
21150 6f 66 20 61 20 71 75 65 72 79 2e 20 20 49 6e 20  of a query.  In 
21160 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
21170 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
21180 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
21190 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
211a0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
211b0 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
211c0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
211d0 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
211e0 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
211f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21200 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
21210 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
21220 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
21230 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
21240 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
21250 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
21260 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
21270 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
21280 64 2e 20 20 54 68 65 20 6c 65 66 74 6d 6f 73 74  d.  The leftmost
21290 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
212a0 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
212b0 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 0a 2a 2a  e index 0..**.**
212c0 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
212d0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
212e0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
212f0 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
21300 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
21310 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
21320 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
21330 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
21340 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
21350 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
21360 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
21370 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
21380 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
21390 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
213a0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
213b0 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
213c0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
213d0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
213e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
213f0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
21400 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
21410 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
21420 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
21430 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
21440 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
21450 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
21460 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
21470 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21480 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
21490 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
214a0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
214b0 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
214c0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
214d0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
214e0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
214f0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
21500 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
21510 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
21520 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
21530 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
21540 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
21550 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
21560 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
21570 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
21580 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
21590 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
215a0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
215b0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
215c0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
215d0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
215e0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
215f0 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
21600 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
21610 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
21620 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
21630 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
21640 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
21650 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
21660 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
21670 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
21680 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
21690 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
216a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
216b0 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
216c0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
216d0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
216e0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
216f0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
21700 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
21710 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
21720 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
21730 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
21740 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
21750 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
21760 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
21770 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
21780 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
21790 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
217a0 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
217b0 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
217c0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rsion..**.** If 
217d0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
217e0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
217f0 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
21800 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
21810 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
21820 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
21830 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
21840 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
21850 6e 67 2e 0a 2a 2a 20 49 66 20 74 68 65 20 72 65  ng..** If the re
21860 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
21870 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
21880 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
21890 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
218a0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
218b0 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
218c0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
218d0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 49 66   of bytes..** If
218e0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
218f0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
21900 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
21910 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
21920 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
21930 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
21940 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
21950 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
21960 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
21970 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
21980 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
21990 67 2e 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  g..** The value 
219a0 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
219b0 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
219c0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74  ro terminator at
219d0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
219e0 68 65 20 73 74 72 69 6e 67 2e 20 20 46 6f 72 20  he string.  For 
219f0 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
21a00 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74  ue returned is t
21a10 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
21a20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
21a30 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
21a40 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
21a50 73 2e 0a 2a 2a 0a 2a 2a 20 53 74 72 69 6e 67 73  s..**.** Strings
21a60 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
21a70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
21a80 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
21a90 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
21aa0 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
21ab0 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
21ac0 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65  s zero terminate
21ad0 64 2e 20 20 54 68 65 20 72 65 74 75 72 6e 0a 2a  d.  The return.*
21ae0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
21af0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
21b00 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
21b10 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20  ngth BLOB is an 
21b20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69  arbitrary.** poi
21b30 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65  nter, possibly e
21b40 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ven a NULL point
21b50 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
21b60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
21b70 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20 69  es16() routine i
21b80 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71 6c  s similar to sql
21b90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
21ba0 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76 65  s().** but leave
21bb0 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 20  s the result in 
21bc0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
21bd0 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73 74   byte order inst
21be0 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a 2a  ead of UTF-8..**
21bf0 20 54 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   The zero termin
21c00 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e 63 6c  ator is not incl
21c10 75 64 65 64 20 69 6e 20 74 68 69 73 20 63 6f 75  uded in this cou
21c20 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 62  nt..**.** The ob
21c30 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
21c40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
21c50 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
21c60 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
21c70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
21c80 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f  bject.  An unpro
21c90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
21ca0 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d  alue object.** m
21cb0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
21cc0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69  with [sqlite3_bi
21cd0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
21ce0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
21cf0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
21d00 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
21d10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
21d20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
21d30 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
21d40 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
21d50 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
21d60 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
21d70 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
21d80 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
21d90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
21da0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
21db0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
21dc0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
21dd0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20  _bytes()], then 
21de0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
21df0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
21e00 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
21e10 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
21e20 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
21e30 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
21e40 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
21e50 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
21e60 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
21e70 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
21e80 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
21e90 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
21ea0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
21eb0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
21ec0 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
21ed0 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
21ee0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
21ef0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
21f00 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
21f10 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
21f20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
21f30 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
21f40 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
21f50 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
21f60 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
21f70 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
21f80 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
21f90 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
21fa0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
21fb0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
21fc0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
21fd0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
21fe0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
21ff0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
22000 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
22010 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
22020 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
22030 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
22040 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
22050 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
22060 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
22070 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
22080 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
22090 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
220a0 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
220b0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
220c0 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
220d0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
220e0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
220f0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
22100 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
22110 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
22120 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
22130 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
22140 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
22150 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
22160 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
22170 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
22180 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
22190 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
221a0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
221b0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
221c0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
221d0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
221e0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
221f0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
22200 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
22210 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
22220 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
22230 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
22240 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
22250 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
22260 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
22270 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
22280 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
22290 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
222a0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
222b0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
222c0 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
222d0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
222e0 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
222f0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
22300 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
22310 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
22320 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
22330 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
22340 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
22350 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
22360 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
22370 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
22380 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
22390 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
223a0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
223b0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
223c0 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
223d0 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
223e0 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
223f0 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
22400 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
22410 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
22420 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
22430 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
22440 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
22450 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
22460 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
22470 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
22480 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
22490 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
224a0 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
224b0 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
224c0 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
224d0 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
224e0 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
224f0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
22500 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
22510 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
22520 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
22530 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
22540 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
22550 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
22560 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
22570 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
22580 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
22590 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
225a0 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
225b0 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
225c0 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
225d0 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
225e0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
225f0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
22600 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
22610 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
22620 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
22630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22640 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
22650 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22660 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
22670 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
22680 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
22690 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
226a0 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
226b0 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
226c0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
226d0 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
226e0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
226f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
22700 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
22710 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
22720 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
22730 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
22740 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
22750 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
22760 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
22770 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
22780 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
22790 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
227a0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
227b0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
227c0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
227d0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
227e0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
227f0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
22800 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
22810 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e   </ul>.**.** Con
22820 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
22830 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
22840 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
22850 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
22860 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
22870 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
22880 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
22890 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
228a0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
228b0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
228c0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70   prior pointer p
228d0 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61  oints to will ha
228e0 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
228f0 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
22900 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
22910 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
22920 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
22930 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
22940 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
22950 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
22960 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
22970 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
22980 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
22990 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
229a0 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
229b0 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
229c0 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
229d0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
229e0 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
229f0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
22a00 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
22a10 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
22a20 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
22a30 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
22a40 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
22a50 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
22a60 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
22a70 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
22a80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
22a90 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
22aa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
22ab0 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
22ac0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22ad0 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
22ae0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
22af0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f   other words, yo
22b00 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71  u should call sq
22b10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
22b20 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t(),.** sqlite3_
22b30 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f  column_blob(), o
22b40 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
22b50 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20  _text16() first 
22b60 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73  to force the res
22b70 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ult.** into the 
22b80 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20  desired format, 
22b90 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69  then invoke sqli
22ba0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
22bb0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
22bc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
22bd0 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69  ) to find the si
22be0 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ze of the result
22bf0 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61  .  Do not mix ca
22c00 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  lls.** to sqlite
22c10 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
22c20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
22c30 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61  n_blob() with ca
22c40 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
22c50 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
22c60 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d  (), and do not m
22c70 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ix calls to sqli
22c80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
22c90 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c  6().** with call
22ca0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
22cb0 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a  umn_bytes()..**.
22cc0 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 73 20  ** The pointers 
22cd0 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
22ce0 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
22cf0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
22d00 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
22d10 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
22d20 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
22d30 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
22d40 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
22d50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
22d60 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  )] is called.  T
22d70 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
22d80 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
22d90 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
22da0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
22db0 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
22dc0 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
22dd0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
22de0 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
22df0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
22e00 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
22e10 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
22e20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
22e30 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ree()]..**.** If
22e40 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
22e50 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
22e60 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
22e70 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
22e80 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
22e90 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
22ea0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
22eb0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
22ec0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
22ed0 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
22ee0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
22ef0 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
22f00 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
22f10 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
22f20 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
22f30 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
22f40 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
22f50 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
22f60 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
22f70 3a 0a 2a 2a 20 5b 48 31 33 38 30 33 5d 20 5b 48  :.** [H13803] [H
22f80 31 33 38 30 36 5d 20 5b 48 31 33 38 30 39 5d 20  13806] [H13809] 
22f90 5b 48 31 33 38 31 32 5d 20 5b 48 31 33 38 31 35  [H13812] [H13815
22fa0 5d 20 5b 48 31 33 38 31 38 5d 20 5b 48 31 33 38  ] [H13818] [H138
22fb0 32 31 5d 20 5b 48 31 33 38 32 34 5d 0a 2a 2a 20  21] [H13824].** 
22fc0 5b 48 31 33 38 32 37 5d 20 5b 48 31 33 38 33 30  [H13827] [H13830
22fd0 5d 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ].*/.const void 
22fe0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
22ff0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
23000 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
23010 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
23020 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
23030 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
23040 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
23050 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
23060 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
23070 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
23080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
23090 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
230a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
230b0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
230c0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
230d0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
230e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
230f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
23100 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
23110 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
23120 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
23130 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23140 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
23150 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
23160 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
23170 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
23180 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23190 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
231a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
231b0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
231c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
231d0 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
231e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
231f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23200 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
23210 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
23220 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
23230 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 20  tatement Object 
23240 7b 48 31 33 33 30 30 7d 20 3c 53 37 30 33 30 30  {H13300} <S70300
23250 3e 3c 53 33 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S30100>.**.** 
23260 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
23270 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
23280 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
23290 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
232a0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49  statement]..** I
232b0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
232c0 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63  was executed suc
232d0 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74  cessfully or not
232e0 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c   executed at all
232f0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45  , then.** SQLITE
23300 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
23310 20 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66   If execution of
23320 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
23330 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a  ailed then an.**
23340 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
23350 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
23360 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
23370 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ed..**.** This r
23380 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
23390 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
233a0 74 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65  t during the exe
233b0 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  cution of the.**
233c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
233d0 6d 65 6e 74 5d 2e 20 20 49 66 20 74 68 65 20 76  ment].  If the v
233e0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68  irtual machine h
233f0 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65  as not.** comple
23400 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68  ted execution wh
23410 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
23420 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20  is called, that 
23430 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75  is like.** encou
23440 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72  ntering an error
23450 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   or an [sqlite3_
23460 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
23470 72 72 75 70 74 5d 2e 0a 2a 2a 20 49 6e 63 6f 6d  rrupt]..** Incom
23480 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61  plete updates ma
23490 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  y be rolled back
234a0 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e   and transaction
234b0 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64  s canceled,.** d
234c0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
234d0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61  circumstances, a
234e0 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72  nd the.** [error
234f0 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20   code] returned 
23500 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  will be [SQLITE_
23510 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  ABORT]..**.** Re
23520 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
23530 48 31 31 33 30 32 5d 20 5b 48 31 31 33 30 34 5d  H11302] [H11304]
23540 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23550 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
23560 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
23570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23580 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
23590 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
235a0 74 20 7b 48 31 33 33 33 30 7d 20 3c 53 37 30 33  t {H13330} <S703
235b0 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  00>.**.** The sq
235c0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
235d0 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
235e0 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
235f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23600 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
23610 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
23620 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
23630 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
23640 2a 20 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d  * Any SQL statem
23650 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
23660 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
23670 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
23680 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
23690 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
236a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
236b0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
236c0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
236d0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
236e0 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
236f0 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
23700 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33 33 32 7d  ..**.** {H11332}
23710 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   The [sqlite3_re
23720 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
23730 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
23740 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
23750 5d 20 53 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ] S.**          
23760 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
23770 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
23780 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  gram..**.** {H11
23790 33 33 34 7d 20 49 66 20 74 68 65 20 6d 6f 73 74  334} If the most
237a0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
237b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
237c0 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  ] for the.**    
237d0 20 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20        [prepared 
237e0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74  statement] S ret
237f0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
23800 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  W] or [SQLITE_DO
23810 4e 45 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20  NE],.**         
23820 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
23830 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
23840 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
23850 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 20  alled on S,.**  
23860 20 20 20 20 20 20 20 20 74 68 65 6e 20 5b 73 71          then [sq
23870 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
23880 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
23890 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31 33  OK]..**.** {H113
238a0 33 36 7d 20 49 66 20 74 68 65 20 6d 6f 73 74 20  36} If the most 
238b0 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
238c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
238d0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
238e0 20 20 20 20 20 5b 70 72 65 70 61 72 65 64 20 73       [prepared s
238f0 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
23900 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
23910 74 68 65 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20  then.**         
23920 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
23930 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
23940 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
23950 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 7b  r code]..**.** {
23960 48 31 31 33 33 38 7d 20 54 68 65 20 5b 73 71 6c  H11338} The [sql
23970 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
23980 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
23990 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
239a0 75 65 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ues.**          
239b0 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
239c0 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
239d0 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
239e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
239f0 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  S..*/.int sqlite
23a00 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
23a10 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
23a20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
23a30 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
23a40 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 20  e SQL Functions 
23a50 7b 48 31 36 31 30 30 7d 20 3c 53 32 30 32 30 30  {H16100} <S20200
23a60 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  >.** KEYWORDS: {
23a70 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
23a80 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
23a90 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
23aa0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
23ab0 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
23ac0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
23ad0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
23ae0 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  L functions}.**.
23af0 2a 2a 20 54 68 65 73 65 20 74 77 6f 20 66 75 6e  ** These two fun
23b00 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
23b10 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
23b20 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
23b30 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
23b40 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
23b50 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
23b60 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
23b70 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
23b80 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
23b90 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
23ba0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
23bb0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
23bc0 66 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20  ference between 
23bd0 74 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68  the.** two is th
23be0 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  at the second pa
23bf0 72 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d  rameter, the nam
23c00 65 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72  e of the (scalar
23c10 29 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  ) function or.**
23c20 20 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65   aggregate, is e
23c30 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20  ncoded in UTF-8 
23c40 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
23c50 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e  te_function() an
23c60 64 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20  d UTF-16.** for 
23c70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
23c80 75 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a  unction16()..**.
23c90 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
23ca0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
23cb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23cc0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
23cd0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
23ce0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
23cf0 20 20 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72    If a single pr
23d00 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20  ogram uses more 
23d10 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
23d20 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
23d30 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e  internally, then
23d40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
23d50 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64  ust be added ind
23d60 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20  ividually to.** 
23d70 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
23d80 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nnection..**.** 
23d90 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
23da0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
23db0 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
23dc0 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
23dd0 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
23de0 65 64 2e 20 20 54 68 65 20 6c 65 6e 67 74 68 20  ed.  The length 
23df0 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
23e00 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
23e10 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  tes, exclusive o
23e20 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65  f.** the zero-te
23e30 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20  rminator.  Note 
23e40 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65  that the name le
23e50 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
23e60 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63   bytes, not.** c
23e70 68 61 72 61 63 74 65 72 73 2e 20 20 41 6e 79 20  haracters.  Any 
23e80 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
23e90 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
23ea0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
23eb0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
23ec0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
23ed0 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
23ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
23ef0 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
23f00 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
23f10 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
23f20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
23f30 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
23f40 65 67 61 74 65 20 74 61 6b 65 73 2e 20 49 66 20  egate takes. If 
23f50 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
23f60 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
23f70 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
23f80 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
23f90 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
23fa0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
23fb0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
23fc0 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
23fd0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
23fe0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
23ff0 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
24000 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
24010 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
24020 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
24030 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
24040 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
24050 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
24060 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
24070 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
24080 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
24090 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
240a0 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
240b0 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
240c0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
240d0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
240e0 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
240f0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
24100 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
24110 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
24120 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
24130 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
24140 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
24150 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
24160 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
24170 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
24180 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
24190 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 41 6e 20  an another.  An 
241a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a  application may.
241b0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
241c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
241d0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
241e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
241f0 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
24200 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
24210 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
24220 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
24230 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
24240 70 2e 0a 2a 2a 20 57 68 65 6e 20 6d 75 6c 74 69  p..** When multi
24250 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
24260 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
24270 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
24280 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
24290 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
242a0 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
242b0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
242c0 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
242d0 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
242e0 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
242f0 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
24300 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
24310 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
24320 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
24330 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
24340 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
24350 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
24360 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  _ANY]..**.** The
24370 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72   fifth parameter
24380 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79   is an arbitrary
24390 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69   pointer.  The i
243a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
243b0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
243c0 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73   can gain access
243d0 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72   to this pointer
243e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
243f0 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 0a 2a 2a  user_data()]..**
24400 0a 2a 2a 20 54 68 65 20 73 65 76 65 6e 74 68 2c  .** The seventh,
24410 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69 6e 74   eighth and nint
24420 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
24430 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
24440 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
24450 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
24460 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
24470 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
24480 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
24490 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
244a0 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  A scalar SQL fun
244b0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
244c0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
244d0 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a   of the xFunc.**
244e0 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 2c 20   callback only, 
244f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 73 68  NULL pointers sh
24500 6f 75 6c 64 20 62 65 20 70 61 73 73 65 64 20 61  ould be passed a
24510 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
24520 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
24530 74 65 72 73 2e 20 41 6e 20 61 67 67 72 65 67 61  ters. An aggrega
24540 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
24550 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
24560 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
24570 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
24580 6c 20 61 6e 64 20 4e 55 4c 4c 20 73 68 6f 75 6c  l and NULL shoul
24590 64 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  d be passed for 
245a0 78 46 75 6e 63 2e 20 54 6f 20 64 65 6c 65 74 65  xFunc. To delete
245b0 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
245c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
245d0 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
245e0 4e 55 4c 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72  NULL for all thr
245f0 65 65 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ee function call
24600 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  backs..**.** It 
24610 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
24620 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c  register multipl
24630 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
24640 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a  s of the same.**
24650 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20   functions with 
24660 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
24670 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69  t with either di
24680 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20  ffering numbers 
24690 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20  of.** arguments 
246a0 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65  or differing pre
246b0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
246c0 64 69 6e 67 73 2e 20 20 53 51 4c 69 74 65 20 77  dings.  SQLite w
246d0 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
246e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
246f0 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
24700 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
24710 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
24720 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
24730 75 73 65 64 2e 20 20 41 20 66 75 6e 63 74 69 6f  used.  A functio
24740 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
24750 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
24760 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
24770 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
24780 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
24790 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
247a0 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
247b0 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
247c0 20 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65    A function whe
247d0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
247e0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
247f0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
24800 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
24810 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
24820 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
24830 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
24840 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
24850 72 65 6e 74 2e 20 20 0a 2a 2a 20 41 20 66 75 6e  rent.  .** A fun
24860 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
24870 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
24880 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55  nce is between U
24890 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36  TF16le and UTF16
248a0 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65  be.** is a close
248b0 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
248c0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
248d0 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
248e0 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77  rence is.** betw
248f0 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46  een UTF8 and UTF
24900 31 36 2e 0a 2a 2a 0a 2a 2a 20 42 75 69 6c 74 2d  16..**.** Built-
24910 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
24920 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
24930 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
24940 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
24950 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ons..** The firs
24960 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  t application-de
24970 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77  fined function w
24980 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65  ith a given name
24990 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a   overrides all.*
249a0 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74  * built-in funct
249b0 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65  ions in the same
249c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
249d0 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20  ction] with the 
249e0 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 53 75  same name..** Su
249f0 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61  bsequent applica
24a00 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
24a10 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ctions of the sa
24a20 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65  me name only ove
24a30 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20  rride .** prior 
24a40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
24a50 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ned functions th
24a60 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20  at are an exact 
24a70 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a  match for the.**
24a80 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d   number of param
24a90 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72  eters and prefer
24aa0 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  red encoding..**
24ab0 0a 2a 2a 20 41 6e 20 61 70 70 6c 69 63 61 74 69  .** An applicati
24ac0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
24ad0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
24ae0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
24af0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
24b00 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
24b10 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
24b20 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
24b30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24b40 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
24b50 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
24b60 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
24b70 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
24b80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
24b90 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ning..**.** Requ
24ba0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
24bb0 36 31 30 33 5d 20 5b 48 31 36 31 30 36 5d 20 5b  6103] [H16106] [
24bc0 48 31 36 31 30 39 5d 20 5b 48 31 36 31 31 32 5d  H16109] [H16112]
24bd0 20 5b 48 31 36 31 31 38 5d 20 5b 48 31 36 31 32   [H16118] [H1612
24be0 31 5d 20 5b 48 31 36 31 32 37 5d 0a 2a 2a 20 5b  1] [H16127].** [
24bf0 48 31 36 31 33 30 5d 20 5b 48 31 36 31 33 33 5d  H16130] [H16133]
24c00 20 5b 48 31 36 31 33 36 5d 20 5b 48 31 36 31 33   [H16136] [H1613
24c10 39 5d 20 5b 48 31 36 31 34 32 5d 0a 2a 2f 0a 69  9] [H16142].*/.i
24c20 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
24c30 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
24c40 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
24c50 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
24c60 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
24c70 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
24c80 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
24c90 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
24ca0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
24cb0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
24cc0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
24cd0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
24ce0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
24cf0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
24d00 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
24d10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
24d20 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
24d30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
24d40 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
24d50 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
24d60 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
24d70 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
24d80 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
24d90 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
24da0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
24db0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
24dc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
24dd0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
24de0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
24df0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
24e00 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
24e10 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
24e20 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a  3_context*).);..
24e30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24e40 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 20 7b  Text Encodings {
24e50 48 31 30 32 36 37 7d 20 3c 53 35 30 32 30 30 3e  H10267} <S50200>
24e60 20 3c 48 31 36 31 30 30 3e 0a 2a 2a 0a 2a 2a 20   <H16100>.**.** 
24e70 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
24e80 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
24e90 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
24ea0 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
24eb0 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
24ec0 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
24ed0 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
24ee0 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
24ef0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
24f00 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
24f10 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
24f20 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
24f30 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
24f40 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
24f50 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
24f60 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
24f70 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
24f80 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
24f90 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
24fa0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24fb0 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
24fc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
24fd0 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
24fe0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
24ff0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
25000 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
25010 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
25020 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
25030 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
25040 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
25050 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
25060 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
25070 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
25080 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
25090 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
250a0 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
250b0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
250c0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
250d0 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
250e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
250f0 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
25100 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
25110 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
25120 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
25130 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
25140 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
25150 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
25160 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
25170 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
25180 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
25190 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
251a0 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
251b0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
251c0 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
251d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
251e0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
251f0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
25200 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
25210 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
25220 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
25230 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
25240 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
25250 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
25260 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
25270 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
25280 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
25290 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
252a0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
252b0 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
252c0 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
252d0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
252e0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
252f0 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
25300 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
25310 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
25320 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
25330 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
25340 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
25350 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
25360 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
25370 65 73 20 7b 48 31 35 31 30 30 7d 20 3c 53 32 30  es {H15100} <S20
25380 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  200>.**.** The C
25390 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
253a0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
253b0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
253c0 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
253d0 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
253e0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
253f0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
25400 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
25410 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
25420 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
25430 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
25440 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
25450 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
25460 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
25470 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
25480 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
25490 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
254a0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
254b0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
254c0 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
254d0 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
254e0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
254f0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
25500 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20  tes..** The 4th 
25510 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
25520 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
25530 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
25540 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
25550 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25560 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
25570 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
25580 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
25590 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
255a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
255b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
255c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
255d0 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
255e0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
255f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
25600 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
25610 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
25620 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
25630 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
25640 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
25650 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
25660 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
25670 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
25680 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
25690 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
256a0 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
256b0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
256c0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ior..**.** These
256d0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
256e0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
256f0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
25700 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
25710 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
25720 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
25730 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
25740 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
25750 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
25760 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
25770 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
25780 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
25790 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
257a0 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
257b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
257c0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
257d0 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
257e0 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
257f0 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
25800 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
25810 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
25820 68 69 6e 65 2e 20 20 54 68 65 0a 2a 2a 20 73 71  hine.  The.** sq
25830 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
25840 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
25850 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
25860 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
25870 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
25880 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
25890 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
258a0 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
258b0 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ively..**.** The
258c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
258d0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
258e0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
258f0 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
25900 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
25910 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
25920 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
25930 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
25940 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
25950 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
25960 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
25970 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
25980 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
25990 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
259a0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
259b0 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
259c0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
259d0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
259e0 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
259f0 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
25a00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
25a10 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
25a20 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
25a30 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
25a40 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
25a50 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
25a60 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
25a70 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
25a80 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 6c  turned..**.** Pl
25a90 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
25aa0 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
25ab0 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
25ac0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
25ad0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
25ae0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
25af0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
25b00 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
25b10 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
25b20 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
25b30 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
25b40 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
25b50 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
25b60 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
25b70 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
25b80 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
25b90 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
25ba0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
25bb0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
25bc0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
25bd0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
25be0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
25bf0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
25c00 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
25c10 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
25c20 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
25c30 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
25c40 72 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  rs..**.** Requir
25c50 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 35 31  ements:.** [H151
25c60 30 33 5d 20 5b 48 31 35 31 30 36 5d 20 5b 48 31  03] [H15106] [H1
25c70 35 31 30 39 5d 20 5b 48 31 35 31 31 32 5d 20 5b  5109] [H15112] [
25c80 48 31 35 31 31 35 5d 20 5b 48 31 35 31 31 38 5d  H15115] [H15118]
25c90 20 5b 48 31 35 31 32 31 5d 20 5b 48 31 35 31 32   [H15121] [H1512
25ca0 34 5d 0a 2a 2a 20 5b 48 31 35 31 32 37 5d 20 5b  4].** [H15127] [
25cb0 48 31 35 31 33 30 5d 20 5b 48 31 35 31 33 33 5d  H15130] [H15133]
25cc0 20 5b 48 31 35 31 33 36 5d 0a 2a 2f 0a 63 6f 6e   [H15136].*/.con
25cd0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
25ce0 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
25cf0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
25d00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
25d10 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
25d20 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
25d30 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
25d40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
25d50 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
25d60 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
25d70 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
25d80 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
25d90 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
25da0 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
25db0 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
25dc0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
25dd0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
25de0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
25df0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
25e00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
25e10 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
25e20 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
25e30 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
25e40 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
25e50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
25e60 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
25e70 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
25e80 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
25e90 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
25ea0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
25eb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
25ec0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
25ed0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
25ee0 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
25ef0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
25f00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25f10 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
25f20 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
25f30 6e 74 65 78 74 20 7b 48 31 36 32 31 30 7d 20 3c  ntext {H16210} <
25f40 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20200>.**.** Th
25f50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
25f60 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
25f70 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
25f80 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
25f90 61 6c 6c 6f 63 61 74 65 0a 2a 2a 20 61 20 73 74  allocate.** a st
25fa0 72 75 63 74 75 72 65 20 66 6f 72 20 73 74 6f 72  ructure for stor
25fb0 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
25fc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
25fd0 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
25fe0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
25ff0 65 78 74 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ext() routine is
26000 20 63 61 6c 6c 65 64 20 66 6f 72 20 61 0a 2a 2a   called for a.**
26010 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
26020 65 67 61 74 65 2c 20 53 51 4c 69 74 65 20 61 6c  egate, SQLite al
26030 6c 6f 63 61 74 65 73 20 6e 42 79 74 65 73 20 6f  locates nBytes o
26040 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
26050 20 6f 75 74 20 74 68 61 74 0a 2a 2a 20 6d 65 6d   out that.** mem
26060 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
26070 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
26080 2e 20 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20  . On second and 
26090 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
260a0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
260b0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
260c0 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
260d0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
260e0 6f 6e 20 69 6e 64 65 78 2c 0a 2a 2a 20 74 68 65  on index,.** the
260f0 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
26100 72 65 74 75 72 6e 65 64 2e 20 54 68 65 20 69 6d  returned. The im
26110 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
26120 74 68 65 20 61 67 67 72 65 67 61 74 65 20 63 61  the aggregate ca
26130 6e 20 75 73 65 0a 2a 2a 20 74 68 65 20 72 65 74  n use.** the ret
26140 75 72 6e 65 64 20 62 75 66 66 65 72 20 74 6f 20  urned buffer to 
26150 61 63 63 75 6d 75 6c 61 74 65 20 64 61 74 61 2e  accumulate data.
26160 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 61 75  .**.** SQLite au
26170 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
26180 73 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  s the allocated 
26190 62 75 66 66 65 72 20 77 68 65 6e 20 74 68 65 20  buffer when the 
261a0 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 71 75 65  aggregate.** que
261b0 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
261c0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
261d0 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62  rameter should b
261e0 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
261f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
26200 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
26210 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
26220 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
26230 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
26240 65 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  e callback routi
26250 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
26260 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
26270 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
26280 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
26290 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
262a0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
262b0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
262c0 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
262d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
262e0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
262f0 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
26300 32 31 31 5d 20 5b 48 31 36 32 31 33 5d 20 5b 48  211] [H16213] [H
26310 31 36 32 31 35 5d 20 5b 48 31 36 32 31 37 5d 0a  16215] [H16217].
26320 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
26330 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
26340 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
26350 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
26360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26370 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
26380 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36 32   Functions {H162
26390 34 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a  40} <S20200>.**.
263a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
263b0 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
263c0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
263d0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
263e0 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
263f0 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
26400 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
26410 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
26420 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
26430 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
26440 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
26450 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26460 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
26470 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
26480 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
26490 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
264a0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 7b  ined function. {
264b0 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  END}.**.** This 
264c0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
264d0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
264e0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
264f0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
26500 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
26510 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
26520 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ing..**.** Requi
26530 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
26540 32 34 33 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  243].*/.void *sq
26550 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
26560 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
26570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26580 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
26590 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
265a0 74 69 6f 6e 73 20 7b 48 31 36 32 35 30 7d 20 3c  tions {H16250} <
265b0 53 36 30 36 30 30 3e 3c 53 32 30 32 30 30 3e 0a  S60600><S20200>.
265c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
265d0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
265e0 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
265f0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
26600 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
26610 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
26620 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
26630 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
26640 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
26650 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
26660 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
26670 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26680 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
26690 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
266a0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
266b0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
266c0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
266d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  tion..**.** Requ
266e0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
266f0 36 32 35 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33  6253].*/.sqlite3
26700 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
26710 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
26720 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
26730 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
26740 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
26750 72 79 20 44 61 74 61 20 7b 48 31 36 32 37 30 7d  ry Data {H16270}
26760 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
26770 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77  The following tw
26780 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  o functions may 
26790 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61  be used by scala
267a0 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  r SQL functions 
267b0 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
267c0 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
267d0 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
267e0 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
267f0 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
26800 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
26810 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
26820 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
26830 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
26840 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
26850 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
26860 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
26870 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
26880 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69  e preserved. Thi
26890 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64  s may.** be used
268a0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74  , for example, t
268b0 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d  o add a regular-
268c0 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
268d0 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75  ing scalar.** fu
268e0 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70  nction. The comp
268f0 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20  iled version of 
26900 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72  the regular expr
26910 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64  ession is stored
26920 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20   as.** metadata 
26930 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
26940 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61  the SQL value pa
26950 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75  ssed as the regu
26960 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a  lar expression.*
26970 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20  * pattern.  The 
26980 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
26990 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
269a0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
269b0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
269c0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
269d0 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61   function so tha
269e0 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70  t the original p
269f0 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a  attern string.**
26a00 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
26a10 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20  o be recompiled 
26a20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  on each invocati
26a30 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  on..**.** The sq
26a40 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
26a50 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
26a60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
26a70 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
26a80 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
26a90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
26aa0 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
26ab0 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
26ac0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
26ad0 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
26ae0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26af0 6e 63 74 69 6f 6e 2e 20 49 66 20 6e 6f 20 6d 65  nction. If no me
26b00 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
26b10 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
26b20 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
26b30 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
26b40 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
26b50 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
26b60 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
26b70 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
26b80 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
26b90 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
26ba0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
26bb0 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
26bc0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
26bd0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
26be0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
26bf0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 61  a() interface sa
26c00 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74 61  ves the metadata
26c10 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
26c20 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  y its 3rd parame
26c30 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61 64  ter as the metad
26c40 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
26c50 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
26c60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
26c70 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26c80 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a  .  Subsequent.**
26c90 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
26ca0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
26cb0 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68 69  might return thi
26cc0 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68 61  s data, if it ha
26cd0 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65  s.** not been de
26ce0 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 49 66 20 69  stroyed..** If i
26cf0 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  t is not NULL, S
26d00 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b  QLite will invok
26d10 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
26d20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76  .** function giv
26d30 65 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61  en by the 4th pa
26d40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
26d50 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
26d60 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64   on.** the metad
26d70 61 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72  ata when the cor
26d80 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
26d90 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
26da0 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e  anges.** or when
26db0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
26dc0 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68  nt completes, wh
26dd0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
26de0 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  rst..**.** SQLit
26df0 65 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c  e is free to cal
26e00 6c 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  l the destructor
26e10 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61   and drop metada
26e20 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72  ta on any.** par
26e30 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75  ameter of any fu
26e40 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69  nction at any ti
26e50 6d 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 67 75  me.  The only gu
26e60 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a  arantee is that.
26e70 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ** the destructo
26e80 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
26e90 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
26ea0 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e  data is dropped.
26eb0 0a 2a 2a 0a 2a 2a 20 49 6e 20 70 72 61 63 74 69  .**.** In practi
26ec0 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
26ed0 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
26ee0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
26ef0 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
26f00 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
26f10 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
26f20 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
26f30 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
26f40 76 61 6c 75 65 73 20 61 6e 64 20 53 51 4c 20 76  values and SQL v
26f50 61 72 69 61 62 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  ariables..**.** 
26f60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
26f70 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
26f80 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
26f90 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
26fa0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
26fb0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
26fc0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
26fd0 2a 2a 20 5b 48 31 36 32 37 32 5d 20 5b 48 31 36  ** [H16272] [H16
26fe0 32 37 34 5d 20 5b 48 31 36 32 37 36 5d 20 5b 48  274] [H16276] [H
26ff0 31 36 32 37 37 5d 20 5b 48 31 36 32 37 38 5d 20  16277] [H16278] 
27000 5b 48 31 36 32 37 39 5d 0a 2a 2f 0a 76 6f 69 64  [H16279].*/.void
27010 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
27020 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
27030 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
27040 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
27050 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
27060 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
27070 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
27080 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
27090 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
270a0 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
270b0 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
270c0 6f 72 20 42 65 68 61 76 69 6f 72 20 7b 48 31 30  or Behavior {H10
270d0 32 38 30 7d 20 3c 53 33 30 31 30 30 3e 0a 2a 2a  280} <S30100>.**
270e0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
270f0 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
27100 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
27110 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
27120 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
27130 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
27140 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
27150 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
27160 28 29 5d 2e 20 20 49 66 20 74 68 65 20 64 65 73  ()].  If the des
27170 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
27180 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
27190 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
271a0 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
271b0 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
271c0 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
271d0 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
271e0 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
271f0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
27200 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f    The.** SQLITE_
27210 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
27220 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
27230 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
27240 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
27250 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
27260 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
27270 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
27280 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
27290 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
272a0 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
272b0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
272c0 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
272d0 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
272e0 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
272f0 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
27300 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
27310 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
27320 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
27330 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
27340 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
27350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
27360 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
27370 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
27380 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
27390 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
273a0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
273b0 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
273c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
273d0 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
273e0 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
273f0 6e 63 74 69 6f 6e 20 7b 48 31 36 34 30 30 7d 20  nction {H16400} 
27400 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20200>.**.** T
27410 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
27420 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
27430 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
27440 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
27450 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
27460 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
27470 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
27480 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
27490 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
274a0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
274b0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
274c0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
274d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
274e0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
274f0 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
27500 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
27510 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
27520 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
27530 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
27540 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
27550 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
27560 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27570 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
27580 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
27590 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
275a0 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
275b0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
275c0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
275d0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69  _result_blob() i
275e0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
275f0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
27600 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
27610 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
27620 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20   to be the BLOB 
27630 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73  whose content is
27640 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62   pointed.** to b
27650 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  y the second par
27660 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68  ameter and which
27670 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67   is N bytes long
27680 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
27690 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
276a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  er..**.** The sq
276b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
276c0 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
276d0 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
276e0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
276f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
27700 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
27710 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
27720 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
27730 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
27740 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
27750 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
27760 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
27770 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  r..**.** The sql
27780 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
27790 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
277a0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
277b0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
277c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
277d0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
277e0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
277f0 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
27800 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
27810 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
27820 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27830 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
27840 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
27850 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
27860 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
27870 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
27880 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
27890 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 53 51  exception..** SQ
278a0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
278b0 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
278c0 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
278d0 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
278e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
278f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
27900 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
27910 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
27920 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
27930 2e 20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70  .  SQLite interp
27940 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
27950 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
27960 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
27970 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
27980 55 54 46 2d 38 2e 20 53 51 4c 69 74 65 0a 2a 2a  UTF-8. SQLite.**
27990 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
279a0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
279b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
279c0 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
279d0 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
279e0 20 6f 72 64 65 72 2e 20 20 49 66 20 74 68 65 20   order.  If the 
279f0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
27a00 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
27a10 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
27a20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27a30 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
27a40 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
27a50 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
27a60 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
27a70 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
27a80 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
27a90 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
27aa0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
27ab0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
27ac0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
27ad0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
27ae0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
27af0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
27b00 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
27b10 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
27b20 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
27b30 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
27b40 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
27b50 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
27b60 65 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  e..** The sqlite
27b70 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
27b80 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
27b90 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
27ba0 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61   routines make a
27bb0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
27bc0 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
27bd0 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a  ge text before.*
27be0 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20  * they return.  
27bf0 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69  Hence, the calli
27c00 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ng function can 
27c10 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a  deallocate or.**
27c20 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74   modify the text
27c30 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75   after they retu
27c40 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  rn without harm.
27c50 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27c60 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
27c70 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
27c80 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
27c90 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
27ca0 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
27cb0 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
27cc0 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
27cd0 20 20 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a    By default,.**
27ce0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
27cf0 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
27d00 20 20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63    A subsequent c
27d10 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
27d20 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
27d30 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
27d40 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73  lt_error16() res
27d50 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ets the error co
27d60 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52  de to SQLITE_ERR
27d70 4f 52 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  OR..**.** The sq
27d80 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
27d90 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
27da0 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
27db0 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
27dc0 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
27dd0 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
27de0 4c 4f 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74  LOB is to long t
27df0 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
27e00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
27e10 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e  esult_nomem() in
27e20 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
27e30 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
27e40 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
27e50 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
27e60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
27e70 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ailed..**.** The
27e80 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27e90 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
27ea0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
27eb0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
27ec0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27ed0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
27ee0 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
27ef0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
27f00 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
27f10 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
27f20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
27f30 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
27f40 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
27f50 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
27f60 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
27f70 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
27f80 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
27f90 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
27fa0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
27fb0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
27fc0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
27fd0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
27fe0 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
27ff0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
28000 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
28010 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
28020 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
28030 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
28040 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
28050 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
28060 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
28070 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
28080 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
28090 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
280a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
280b0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
280c0 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
280d0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
280e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
280f0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
28100 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
28110 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
28120 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
28130 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
28140 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
28150 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
28160 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
28170 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
28180 69 76 65 6c 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  ively..** SQLite
28190 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
281a0 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
281b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
281c0 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
281d0 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
281e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
281f0 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
28200 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
28210 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
28220 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
28230 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
28240 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
28250 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
28260 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
28270 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
28280 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
28290 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
282a0 61 63 74 65 72 2e 0a 2a 2a 20 49 66 20 74 68 65  acter..** If the
282b0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
282c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
282d0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
282e0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
282f0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
28300 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
28310 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
28320 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
28330 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
28340 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
28350 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
28360 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
28370 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
28380 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20  sult..** If the 
28390 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
283a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
283b0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
283c0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
283d0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
283e0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
283f0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
28400 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
28410 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
28420 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
28430 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
28440 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
28450 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
28460 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
28470 0a 2a 2a 20 49 66 20 74 68 65 20 34 74 68 20 70  .** If the 4th p
28480 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
28490 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
284a0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
284b0 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  or to.** sqlite3
284c0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
284d0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
284e0 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
284f0 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  IC, then SQLite.
28500 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ** assumes that 
28510 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
28520 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f   result is in co
28530 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
28540 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70   does not.** cop
28550 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
28560 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e   the parameter n
28570 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
28580 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74  ctor on the cont
28590 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68  ent.** when it h
285a0 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
285b0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
285c0 2a 20 49 66 20 74 68 65 20 34 74 68 20 70 61 72  * If the 4th par
285d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
285e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
285f0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
28600 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
28610 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
28620 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
28630 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
28640 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
28650 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
28660 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
28670 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
28680 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
28690 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
286a0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
286b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
286c0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
286d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
286e0 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
286f0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
28700 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
28710 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
28720 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
28730 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28740 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
28750 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
28760 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 0a  parameter.  The.
28770 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
28780 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
28790 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ace makes a copy
287a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
287b0 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68  _value].** so th
287c0 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
287d0 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64  value] specified
287e0 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
287f0 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a  r may change or.
28800 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ** be deallocate
28810 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
28820 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72  result_value() r
28830 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68  eturns without h
28840 61 72 6d 2e 0a 2a 2a 20 41 20 5b 70 72 6f 74 65  arm..** A [prote
28850 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
28860 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
28870 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
28880 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
28890 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
288a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
288b0 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
288c0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
288d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
288e0 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
288f0 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
28900 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
28910 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
28920 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
28930 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
28940 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
28950 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
28960 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
28970 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
28980 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
28990 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
289a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
289b0 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
289c0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
289d0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
289e0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 34 30 33  ents:.** [H16403
289f0 5d 20 5b 48 31 36 34 30 36 5d 20 5b 48 31 36 34  ] [H16406] [H164
28a00 30 39 5d 20 5b 48 31 36 34 31 32 5d 20 5b 48 31  09] [H16412] [H1
28a10 36 34 31 35 5d 20 5b 48 31 36 34 31 38 5d 20 5b  6415] [H16418] [
28a20 48 31 36 34 32 31 5d 20 5b 48 31 36 34 32 34 5d  H16421] [H16424]
28a30 0a 2a 2a 20 5b 48 31 36 34 32 37 5d 20 5b 48 31  .** [H16427] [H1
28a40 36 34 33 30 5d 20 5b 48 31 36 34 33 33 5d 20 5b  6430] [H16433] [
28a50 48 31 36 34 33 36 5d 20 5b 48 31 36 34 33 39 5d  H16436] [H16439]
28a60 20 5b 48 31 36 34 34 32 5d 20 5b 48 31 36 34 34   [H16442] [H1644
28a70 35 5d 20 5b 48 31 36 34 34 38 5d 0a 2a 2a 20 5b  5] [H16448].** [
28a80 48 31 36 34 35 31 5d 20 5b 48 31 36 34 35 34 5d  H16451] [H16454]
28a90 20 5b 48 31 36 34 35 37 5d 20 5b 48 31 36 34 36   [H16457] [H1646
28aa0 30 5d 20 5b 48 31 36 34 36 33 5d 0a 2a 2f 0a 76  0] [H16463].*/.v
28ab0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
28ac0 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
28ad0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
28ae0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
28af0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
28b00 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
28b10 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
28b20 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
28b30 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
28b40 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
28b50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
28b60 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
28b70 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
28b80 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
28b90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
28ba0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
28bb0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
28bc0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
28bd0 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
28be0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
28bf0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
28c00 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
28c10 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
28c20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
28c30 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
28c40 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
28c50 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
28c60 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
28c70 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
28c80 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
28c90 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
28ca0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
28cb0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
28cc0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
28cd0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
28ce0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
28cf0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
28d00 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
28d10 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
28d20 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
28d30 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
28d40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
28d50 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
28d60 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
28d70 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
28d80 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
28d90 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
28da0 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
28db0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
28dc0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
28dd0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
28de0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
28df0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
28e00 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
28e10 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
28e20 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
28e30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
28e40 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
28e50 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
28e60 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
28e70 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
28e80 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
28e90 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
28ea0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
28eb0 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
28ec0 6e 67 20 53 65 71 75 65 6e 63 65 73 20 7b 48 31  ng Sequences {H1
28ed0 36 36 30 30 7d 20 3c 53 32 30 33 30 30 3e 0a 2a  6600} <S20300>.*
28ee0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
28ef0 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
28f00 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69   add new collati
28f10 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20  on sequences to 
28f20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
28f30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
28f40 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
28f50 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
28f60 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
28f70 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f  the new collatio
28f80 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70  n sequence is sp
28f90 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46  ecified as a UTF
28fa0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72  -8 string.** for
28fb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
28fc0 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20  collation() and 
28fd0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
28fe0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a  ollation_v2().**
28ff0 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74   and a UTF-16 st
29000 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33  ring for sqlite3
29010 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
29020 6e 31 36 28 29 2e 20 49 6e 20 61 6c 6c 20 63 61  n16(). In all ca
29030 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  ses.** the name 
29040 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  is passed as the
29050 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
29060 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
29070 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
29080 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ent may be one o
29090 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20  f the constants 
290a0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
290b0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
290c0 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
290d0 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74  TF16BE], indicat
290e0 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65  ing that the use
290f0 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f  r-supplied.** ro
29100 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f  utine expects to
29110 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74   be passed point
29120 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65  ers to strings e
29130 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
29140 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  -8,.** UTF-16 li
29150 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle-endian, or 
29160 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
29170 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
29180 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72   The.** third ar
29190 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73  gument might als
291a0 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  o be [SQLITE_UTF
291b0 31 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20  16] to indicate 
291c0 74 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65  that the routine
291d0 0a 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e  .** expects poin
291e0 74 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31  ters to be UTF-1
291f0 36 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65  6 strings in the
29200 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
29210 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72  er, or the.** ar
29220 67 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53  gument can be [S
29230 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
29240 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74  NED] if the.** t
29250 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63  he routine expec
29260 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31  ts pointers to 1
29270 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e  6-bit word align
29280 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66  ed strings.** of
29290 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
292a0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
292b0 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ..**.** A pointe
292c0 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75  r to the user su
292d0 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d  pplied routine m
292e0 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
292f0 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72   the fifth.** ar
29300 67 75 6d 65 6e 74 2e 20 20 49 66 20 69 74 20 69  gument.  If it i
29310 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20  s NULL, this is 
29320 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65  the same as dele
29330 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69  ting the collati
29340 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28  on.** sequence (
29350 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  so that SQLite c
29360 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e  annot call it an
29370 79 6d 6f 72 65 29 2e 0a 2a 2a 20 45 61 63 68 20  ymore)..** Each 
29380 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63 61  time the applica
29390 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66 75  tion supplied fu
293a0 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
293b0 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64 0a  d, it is passed.
293c0 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74 20  ** as its first 
293d0 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70 79  parameter a copy
293e0 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 61   of the void* pa
293f0 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
29400 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
29410 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
29420 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72 20  _collation() or 
29430 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
29440 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
29450 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
29460 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  g arguments to t
29470 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  he application-s
29480 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20  upplied routine 
29490 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67 73 2c  are two strings,
294a0 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65 73 65  .** each represe
294b0 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e 67 74  nted by a (lengt
294c0 68 2c 20 64 61 74 61 29 20 70 61 69 72 20 61 6e  h, data) pair an
294d0 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74 68 65  d encoded in the
294e0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74 68 61   encoding.** tha
294f0 74 20 77 61 73 20 70 61 73 73 65 64 20 61 73 20  t was passed as 
29500 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
29510 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f 6c 6c  nt when the coll
29520 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 77  ation sequence w
29530 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  as.** registered
29540 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 61 70 70  . {END}  The app
29550 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
29560 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69   collation routi
29570 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ne should.** ret
29580 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65  urn negative, ze
29590 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69  ro or positive i
295a0 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69  f the first stri
295b0 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c  ng is less than,
295c0 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  .** equal to, or
295d0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
295e0 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e  e second string.
295f0 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d   i.e. (STRING1 -
29600 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a   STRING2)..**.**
29610 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   The sqlite3_cre
29620 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
29630 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
29640 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
29650 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65  lation().** exce
29660 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73  pt that it takes
29670 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65   an extra argume
29680 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65  nt which is a de
29690 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20  structor for.** 
296a0 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20  the collation.  
296b0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
296c0 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  s called when th
296d0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a  e collation is.*
296e0 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20  * destroyed and 
296f0 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
29700 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
29710 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70  arameter void* p
29720 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65  ointer.** of the
29730 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
29740 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a  collation_v2()..
29750 2a 2a 20 43 6f 6c 6c 61 74 69 6f 6e 73 20 61 72  ** Collations ar
29760 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65 6e  e destroyed when
29770 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69   they are overri
29780 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63 61  dden by later ca
29790 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63 6f  lls to the.** co
297a0 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  llation creation
297b0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68   functions or wh
297c0 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  en the [database
297d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
297e0 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67 20  closed.** using 
297f0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
29800 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
29810 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
29820 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
29830 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
29840 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
29850 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ()]..**.** Requi
29860 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36  rements:.** [H16
29870 36 30 33 5d 20 5b 48 31 36 36 30 34 5d 20 5b 48  603] [H16604] [H
29880 31 36 36 30 36 5d 20 5b 48 31 36 36 30 39 5d 20  16606] [H16609] 
29890 5b 48 31 36 36 31 32 5d 20 5b 48 31 36 36 31 35  [H16612] [H16615
298a0 5d 20 5b 48 31 36 36 31 38 5d 20 5b 48 31 36 36  ] [H16618] [H166
298b0 32 31 5d 0a 2a 2a 20 5b 48 31 36 36 32 34 5d 20  21].** [H16624] 
298c0 5b 48 31 36 36 32 37 5d 20 5b 48 31 36 36 33 30  [H16627] [H16630
298d0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
298e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
298f0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
29900 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
29910 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
29920 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
29930 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
29940 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
29950 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
29960 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
29970 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
29980 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
29990 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
299a0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
299b0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
299c0 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a    void*,.  int(*
299d0 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
299e0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
299f0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
29a00 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
29a10 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
29a20 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
29a30 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
29a40 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
29a50 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a  st void *zName,.
29a60 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
29a70 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28  .  void*,.  int(
29a80 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
29a90 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
29aa0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
29ab0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
29ac0 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20  3REF: Collation 
29ad0 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73  Needed Callbacks
29ae0 20 7b 48 31 36 37 30 30 7d 20 3c 53 32 30 33 30   {H16700} <S2030
29af0 30 3e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69  0>.**.** To avoi
29b00 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
29b10 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
29b20 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
29b30 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
29b40 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
29b50 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
29b60 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
29b70 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
29b80 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
29b90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
29ba0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 65   be called whene
29bb0 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64  ver an undefined
29bc0 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
29bd0 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72  quence is requir
29be0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ed..**.** If the
29bf0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
29c00 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
29c10 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
29c20 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
29c30 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
29c40 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
29c50 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
29c60 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
29c70 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
29c80 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
29c90 2e 20 7b 48 31 36 37 30 33 7d 20 49 66 20 73 71  . {H16703} If sq
29ca0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
29cb0 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73  needed16() is us
29cc0 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73  ed,.** the names
29cd0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55   are passed as U
29ce0 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65  TF-16 in machine
29cf0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
29d00 65 72 2e 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  er..** A call to
29d10 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
29d20 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78   replaces any ex
29d30 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e  isting callback.
29d40 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
29d50 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
29d60 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
29d70 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
29d80 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
29d90 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
29da0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
29db0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
29dc0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
29dd0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
29de0 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
29df0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
29e00 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
29e10 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
29e20 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
29e30 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
29e40 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
29e50 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
29e60 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
29e70 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
29e80 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
29e90 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
29ea0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
29eb0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
29ec0 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
29ed0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
29ee0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
29ef0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
29f00 6e 20 73 65 71 75 65 6e 63 65 2e 0a 2a 2a 0a 2a  n sequence..**.*
29f10 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
29f20 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
29f30 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
29f40 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
29f50 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
29f60 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
29f70 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
29f80 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
29f90 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
29fa0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
29fb0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  tion_v2()]..**.*
29fc0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
29fd0 2a 2a 20 5b 48 31 36 37 30 32 5d 20 5b 48 31 36  ** [H16702] [H16
29fe0 37 30 34 5d 20 5b 48 31 36 37 30 36 5d 0a 2a 2f  704] [H16706].*/
29ff0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2a000 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a 20  lation_needed(. 
2a010 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2a020 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  id*, .  void(*)(
2a030 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
2a040 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
2a050 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74 20  t char*).);.int 
2a060 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2a070 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71  n_needed16(.  sq
2a080 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a  lite3*, .  void*
2a090 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ,.  void(*)(void
2a0a0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
2a0b0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f  TextRep,const vo
2a0c0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  id*).);../*.** S
2a0d0 70 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66  pecify the key f
2a0e0 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20  or an encrypted 
2a0f0 64 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20  database.  This 
2a100 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62  routine should b
2a110 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68  e.** called righ
2a120 74 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  t after sqlite3_
2a130 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  open()..**.** Th
2a140 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
2a150 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
2a160 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
2a170 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
2a180 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
2a190 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2a1a0 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20  _key(.  sqlite3 
2a1b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2a1c0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2a1d0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
2a1e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2a1f0 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79   *pKey, int nKey
2a200 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20       /* The key 
2a210 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61  */.);../*.** Cha
2a220 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61  nge the key on a
2a230 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e  n open database.
2a240 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74    If the current
2a250 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74   database is not
2a260 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74  .** encrypted, t
2a270 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c  his routine will
2a280 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66   encrypt it.  If
2a290 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77   pNew==0 or nNew
2a2a0 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61  ==0, the.** data
2a2b0 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65  base is decrypte
2a2c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  d..**.** The cod
2a2d0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
2a2e0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
2a2f0 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
2a300 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
2a310 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
2a320 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
2a330 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
2a340 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2a350 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2a360 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
2a370 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
2a380 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
2a390 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
2a3a0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2a3b0 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20  PI3REF: Suspend 
2a3c0 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20  Execution For A 
2a3d0 53 68 6f 72 74 20 54 69 6d 65 20 7b 48 31 30 35  Short Time {H105
2a3e0 33 30 7d 20 3c 53 34 30 34 31 30 3e 0a 2a 2a 0a  30} <S40410>.**.
2a3f0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
2a400 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20  leep() function 
2a410 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
2a420 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
2a430 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
2a440 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
2a450 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
2a460 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
2a470 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
2a480 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
2a490 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
2a4a0 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
2a4b0 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
2a4c0 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
2a4d0 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
2a4e0 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
2a4f0 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
2a500 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
2a510 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
2a520 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
2a530 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
2a540 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a  sleep actually.*
2a550 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
2a560 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
2a570 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
2a580 64 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  d..**.** SQLite 
2a590 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
2a5a0 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
2a5b0 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
2a5c0 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
2a5d0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
2a5e0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
2a5f0 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
2a600 6e 74 73 3a 20 5b 48 31 30 35 33 33 5d 20 5b 48  nts: [H10533] [H
2a610 31 30 35 33 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71  10536].*/.int sq
2a620 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
2a630 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a640 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
2a650 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
2a660 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 20 7b 48  mporary Files {H
2a670 31 30 33 31 30 7d 20 3c 53 32 30 30 30 30 3e 0a  10310} <S20000>.
2a680 2a 2a 0a 2a 2a 20 49 66 20 74 68 69 73 20 67 6c  **.** If this gl
2a690 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
2a6a0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
2a6b0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
2a6c0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
2a6d0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
2a6e0 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
2a6f0 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61  then all tempora
2a700 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61  ry files.** crea
2a710 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 69  ted by SQLite wi
2a720 6c 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20  ll be placed in 
2a730 74 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 20  that directory. 
2a740 20 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   If this variabl
2a750 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  e.** is a NULL p
2a760 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
2a770 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73  ite performs a s
2a780 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
2a790 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70  ropriate.** temp
2a7a0 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63  orary file direc
2a7b0 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
2a7c0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
2a7d0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
2a7e0 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f  s variable in mo
2a7f0 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74  re than one.** t
2a800 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e  hread at a time.
2a810 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65    It is not safe
2a820 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
2a830 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
2a840 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61  .** if a [databa
2a850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2a860 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20  s being used at 
2a870 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e  the same time in
2a880 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74   a separate.** t
2a890 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20  hread..** It is 
2a8a0 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
2a8b0 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
2a8c0 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
2a8d0 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
2a8e0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
2a8f0 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
2a900 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
2a910 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
2a920 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68  en called and th
2a930 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
2a940 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
2a950 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e  d.** thereafter.
2a960 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 74 65 6d 70  .**.** The [temp
2a970 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
2a980 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
2a990 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
2a9a0 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
2a9b0 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
2a9c0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2a9d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2a9e0 6f 63 5d 2e 20 20 46 75 72 74 68 65 72 6d 6f 72  oc].  Furthermor
2a9f0 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
2aa00 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
2aa10 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
2aa20 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
2aa30 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
2aa40 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
2aa50 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
2aa60 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
2aa70 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
2aa80 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
2aa90 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
2aaa0 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
2aab0 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
2aac0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
2aad0 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
2aae0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
2aaf0 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
2ab00 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
2ab10 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
2ab20 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
2ab30 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
2ab40 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2ab50 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
2ab60 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
2ab70 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
2ab80 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
2ab90 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
2aba0 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51  e avoided..*/.SQ
2abb0 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
2abc0 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
2abd0 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
2abe0 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
2abf0 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20  For Auto-Commit 
2ac00 4d 6f 64 65 20 7b 48 31 32 39 33 30 7d 20 3c 53  Mode {H12930} <S
2ac10 36 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  60200>.** KEYWOR
2ac20 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20  DS: {autocommit 
2ac30 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 20  mode}.**.** The 
2ac40 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
2ac50 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
2ac60 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
2ac70 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
2ac80 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
2ac90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2aca0 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
2acb0 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
2acc0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2acd0 2e 20 20 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  .  Autocommit mo
2ace0 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  de is on by defa
2acf0 75 6c 74 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d  ult..** Autocomm
2ad00 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
2ad10 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
2ad20 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 41   statement..** A
2ad30 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2ad40 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
2ad50 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
2ad60 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
2ad70 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
2ad80 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
2ad90 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
2ada0 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
2adb0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
2adc0 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
2add0 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
2ade0 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
2adf0 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
2ae00 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
2ae10 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
2ae20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2ae30 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
2ae40 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
2ae50 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
2ae60 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2ae70 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
2ae80 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
2ae90 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
2aea0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
2aeb0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2aec0 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
2aed0 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
2aee0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
2aef0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
2af00 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
2af10 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
2af20 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
2af30 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
2af40 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
2af50 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
2af60 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
2af70 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
2af80 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2af90 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48  Requirements: [H
2afa0 31 32 39 33 31 5d 20 5b 48 31 32 39 33 32 5d 20  12931] [H12932] 
2afb0 5b 48 31 32 39 33 33 5d 20 5b 48 31 32 39 33 34  [H12933] [H12934
2afc0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
2afd0 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28  _get_autocommit(
2afe0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
2aff0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
2b000 20 54 68 65 20 44 61 74 61 62 61 73 65 20 48 61   The Database Ha
2b010 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70 61 72  ndle Of A Prepar
2b020 65 64 20 53 74 61 74 65 6d 65 6e 74 20 7b 48 31  ed Statement {H1
2b030 33 31 32 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a  3120} <S60600>.*
2b040 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2b050 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65 72  _db_handle inter
2b060 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2b070 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2b080 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a  ction] handle.**
2b090 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72 65   to which a [pre
2b0a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b0b0 20 62 65 6c 6f 6e 67 73 2e 20 20 54 68 65 20 5b   belongs.  The [
2b0c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b0d0 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ion].** returned
2b0e0 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62 5f 68   by sqlite3_db_h
2b0f0 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73 61 6d  andle is the sam
2b100 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2b110 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 77 61 73  ection] that was
2b120 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2b130 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ent.** to the [s
2b140 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b150 32 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74  2()] call (or it
2b160 73 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74  s variants) that
2b170 20 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20   was used to.** 
2b180 63 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65  create the state
2b190 6d 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73  ment in the firs
2b1a0 74 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52  t place..**.** R
2b1b0 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31  equirements: [H1
2b1c0 33 31 32 33 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33  3123].*/.sqlite3
2b1d0 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e   *sqlite3_db_han
2b1e0 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dle(sqlite3_stmt
2b1f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2b200 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65  REF: Find the ne
2b210 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  xt prepared stat
2b220 65 6d 65 6e 74 20 7b 48 31 33 31 34 30 7d 20 3c  ement {H13140} <
2b230 53 36 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S60600>.**.** Th
2b240 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
2b250 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2b260 6f 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70  o the next [prep
2b270 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2b280 61 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61  after.** pStmt a
2b290 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
2b2a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2b2b0 6e 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 49  nection] pDb.  I
2b2c0 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a  f pStmt is NULL.
2b2d0 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74  ** then this int
2b2e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2b2f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2b300 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73  first prepared s
2b310 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f  tatement.** asso
2b320 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2b330 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b340 69 6f 6e 20 70 44 62 2e 20 20 49 66 20 6e 6f 20  ion pDb.  If no 
2b350 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b360 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20  nt.** satisfies 
2b370 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f  the conditions o
2b380 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
2b390 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e  it returns NULL.
2b3a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61  .**.** The [data
2b3b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b3c0 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20   pointer D in a 
2b3d0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2b3e0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c  te3_next_stmt(D,
2b3f0 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74  S)] must refer t
2b400 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  o an open databa
2b410 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
2b420 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c   and in particul
2b430 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61  ar must not be a
2b440 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2b450 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2b460 73 3a 20 5b 48 31 33 31 34 33 5d 20 5b 48 31 33  s: [H13143] [H13
2b470 31 34 36 5d 20 5b 48 31 33 31 34 39 5d 20 5b 48  146] [H13149] [H
2b480 31 33 31 35 32 5d 0a 2a 2f 0a 73 71 6c 69 74 65  13152].*/.sqlite
2b490 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f  3_stmt *sqlite3_
2b4a0 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65  next_stmt(sqlite
2b4b0 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f  3 *pDb, sqlite3_
2b4c0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2b4d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2b4e0 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61  ommit And Rollba
2b4f0 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20  ck Notification 
2b500 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 35  Callbacks {H1295
2b510 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a  0} <S60400>.**.*
2b520 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
2b530 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
2b540 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
2b550 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
2b560 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
2b570 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
2b580 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
2b590 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74  COMMIT | committ
2b5a0 65 64 5d 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c  ed]..** Any call
2b5b0 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72  back set by a pr
2b5c0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73  evious call to s
2b5d0 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
2b5e0 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ok().** for the 
2b5f0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
2b600 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
2b610 72 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 73  ridden..** The s
2b620 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f  qlite3_rollback_
2b630 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
2b640 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
2b650 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
2b660 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  n to be invoked 
2b670 77 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73  whenever a trans
2b680 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42  action is [ROLLB
2b690 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63  ACK | rolled bac
2b6a0 6b 5d 2e 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62  k]..** Any callb
2b6b0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
2b6c0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
2b6d0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2b6e0 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  k().** for the s
2b6f0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2b700 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2b710 69 64 64 65 6e 2e 0a 2a 2a 20 54 68 65 20 70 41  idden..** The pA
2b720 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70  rg argument is p
2b730 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f  assed through to
2b740 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2b750 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63  * If the callbac
2b760 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f  k on a commit ho
2b770 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  ok function retu
2b780 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a  rns non-zero,.**
2b790 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74   then the commit
2b7a0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e   is converted in
2b7b0 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  to a rollback..*
2b7c0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
2b7d0 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72 65  function was pre
2b7e0 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
2b7f0 65 64 2c 20 69 74 73 0a 2a 2a 20 70 41 72 67 20  ed, its.** pArg 
2b800 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
2b810 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e 55  d.  Otherwise NU
2b820 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  LL is returned..
2b830 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
2b840 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
2b850 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
2b860 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
2b870 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
2b880 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b890 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
2b8a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
2b8b0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
2b8c0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2b8d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2b8e0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
2b8f0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
2b900 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
2b910 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
2b920 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
2b930 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
2b940 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
2b950 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
2b960 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
2b970 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
2b980 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2b990 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
2b9a0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
2b9b0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
2b9c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2b9d0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
2b9e0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
2b9f0 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
2ba00 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 69 6e  **.** Registerin
2ba10 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f  g a NULL functio
2ba20 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  n disables the c
2ba30 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57  allback..**.** W
2ba40 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
2ba50 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  ook callback rou
2ba60 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
2ba70 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a  o, the [COMMIT].
2ba80 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ** operation is 
2ba90 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69  allowed to conti
2baa0 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 49  nue normally.  I
2bab0 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f  f the commit hoo
2bac0 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e  k.** returns non
2bad0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
2bae0 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76  [COMMIT] is conv
2baf0 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f  erted into a [RO
2bb00 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 54 68 65 20  LLBACK]..** The 
2bb10 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73  rollback hook is
2bb20 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f   invoked on a ro
2bb30 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75  llback that resu
2bb40 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69  lts from a commi
2bb50 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e  t.** hook return
2bb60 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75  ing non-zero, ju
2bb70 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62  st as it would b
2bb80 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72  e with any other
2bb90 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
2bba0 20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65   For the purpose
2bbb0 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
2bbc0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2bbd0 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
2bbe0 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  n.** rolled back
2bbf0 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
2bc00 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
2bc10 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
2bc20 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
2bc30 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
2bc40 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
2bc50 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
2bc60 63 75 72 2e 0a 2a 2a 20 54 68 65 20 72 6f 6c 6c  cur..** The roll
2bc70 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
2bc80 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
2bc90 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2bca0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
2bcb0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  y rolled back be
2bcc0 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
2bcd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2bce0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 54 68 65 20   closed..** The 
2bcf0 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
2bd00 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
2bd10 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
2bd20 6e 20 69 73 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  n is.** rolled b
2bd30 61 63 6b 20 62 65 63 61 75 73 65 20 61 20 63 6f  ack because a co
2bd40 6d 6d 69 74 20 63 61 6c 6c 62 61 63 6b 20 72 65  mmit callback re
2bd50 74 75 72 6e 65 64 20 6e 6f 6e 2d 7a 65 72 6f 2e  turned non-zero.
2bd60 0a 2a 2a 20 3c 74 6f 64 6f 3e 20 43 68 65 63 6b  .** <todo> Check
2bd70 20 6f 6e 20 74 68 69 73 20 3c 2f 74 6f 64 6f 3e   on this </todo>
2bd80 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
2bd90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64  the [sqlite3_upd
2bda0 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65  ate_hook()] inte
2bdb0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  rface..**.** Req
2bdc0 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
2bdd0 31 32 39 35 31 5d 20 5b 48 31 32 39 35 32 5d 20  12951] [H12952] 
2bde0 5b 48 31 32 39 35 33 5d 20 5b 48 31 32 39 35 34  [H12953] [H12954
2bdf0 5d 20 5b 48 31 32 39 35 35 5d 0a 2a 2a 20 5b 48  ] [H12955].** [H
2be00 31 32 39 36 31 5d 20 5b 48 31 32 39 36 32 5d 20  12961] [H12962] 
2be10 5b 48 31 32 39 36 33 5d 20 5b 48 31 32 39 36 34  [H12963] [H12964
2be20 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ].*/.void *sqlit
2be30 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
2be40 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
2be50 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
2be60 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
2be70 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
2be80 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
2be90 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
2bea0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2beb0 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
2bec0 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
2bed0 6b 73 20 7b 48 31 32 39 37 30 7d 20 3c 53 36 30  ks {H12970} <S60
2bee0 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  400>.**.** The s
2bef0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2bf00 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2bf10 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2bf20 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
2bf30 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
2bf40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2bf50 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2bf60 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
2bf70 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2bf80 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
2bf90 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2bfa0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2bfb0 0a 2a 2a 20 41 6e 79 20 63 61 6c 6c 62 61 63 6b  .** Any callback
2bfc0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
2bfd0 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
2bfe0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  function.** for 
2bff0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2c000 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2c010 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
2c020 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
2c030 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2c040 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
2c050 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
2c060 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70  n a.** row is up
2c070 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
2c080 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 54  or deleted..** T
2c090 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2c0a0 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
2c0b0 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
2c0c0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2c0d0 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
2c0e0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a  update_hook()..*
2c0f0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c  * The second cal
2c100 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
2c110 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2c120 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54  _INSERT], [SQLIT
2c130 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72  E_DELETE],.** or
2c140 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
2c150 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
2c160 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
2c170 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
2c180 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69  lback.** to be i
2c190 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 74  nvoked..** The t
2c1a0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
2c1b0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
2c1c0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
2c1d0 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  n pointers to th
2c1e0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e  e.** database an
2c1f0 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e  d table name con
2c200 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65  taining the affe
2c210 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 54 68 65  cted row..** The
2c220 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
2c230 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2c240 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
2c250 72 6f 77 2e 0a 2a 2a 20 49 6e 20 74 68 65 20 63  row..** In the c
2c260 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74 65  ase of an update
2c270 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b 72  , this is the [r
2c280 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65 20  owid] after the 
2c290 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c 61  update takes pla
2c2a0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70  ce..**.** The up
2c2b0 64 61 74 65 20 68 6f 6f 6b 20 69 73 20 6e 6f 74  date hook is not
2c2c0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 69 6e   invoked when in
2c2d0 74 65 72 6e 61 6c 20 73 79 73 74 65 6d 20 74 61  ternal system ta
2c2e0 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d 6f 64 69  bles are.** modi
2c2f0 66 69 65 64 20 28 69 2e 65 2e 20 73 71 6c 69 74  fied (i.e. sqlit
2c300 65 5f 6d 61 73 74 65 72 20 61 6e 64 20 73 71 6c  e_master and sql
2c310 69 74 65 5f 73 65 71 75 65 6e 63 65 29 2e 0a 2a  ite_sequence)..*
2c320 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 63 75 72 72  *.** In the curr
2c330 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
2c340 6f 6e 2c 20 74 68 65 20 75 70 64 61 74 65 20 68  on, the update h
2c350 6f 6f 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e  ook.** is not in
2c360 76 6f 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69  voked when dupli
2c370 63 61 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20  cation rows are 
2c380 64 65 6c 65 74 65 64 20 62 65 63 61 75 73 65 20  deleted because 
2c390 6f 66 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e  of an.** [ON CON
2c3a0 46 4c 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c  FLICT | ON CONFL
2c3b0 49 43 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61  ICT REPLACE] cla
2c3c0 75 73 65 2e 20 20 4e 6f 72 20 69 73 20 74 68 65  use.  Nor is the
2c3d0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
2c3e0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77  invoked when row
2c3f0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73  s are deleted us
2c400 69 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74  ing the [truncat
2c410 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e  e optimization].
2c420 0a 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f  .** The exceptio
2c430 6e 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68  ns defined in th
2c440 69 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67  is paragraph mig
2c450 68 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66  ht change in a f
2c460 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65  uture.** release
2c470 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
2c480 2a 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  * The update hoo
2c490 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
2c4a0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
2c4b0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
2c4c0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
2c4d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2c4e0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
2c4f0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20  he update hook. 
2c500 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
2c510 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
2c520 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2c530 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
2c540 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
2c550 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
2c560 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2c570 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
2c580 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
2c590 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a   update hook..**
2c5a0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
2c5b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2c5c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
2c5d0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
2c5e0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
2c5f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2c600 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
2c610 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
2c620 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
2c630 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
2c640 20 66 75 6e 63 74 69 6f 6e 20 77 61 73 20 70 72   function was pr
2c650 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65  eviously registe
2c660 72 65 64 2c 20 69 74 73 20 70 41 72 67 20 76 61  red, its pArg va
2c670 6c 75 65 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  lue.** is return
2c680 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 4e  ed.  Otherwise N
2c690 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2c6a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
2c6b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d  the [sqlite3_com
2c6c0 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e 64 20  mit_hook()] and 
2c6d0 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  [sqlite3_rollbac
2c6e0 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69 6e 74  k_hook()].** int
2c6f0 65 72 66 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 52  erfaces..**.** R
2c700 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
2c710 5b 48 31 32 39 37 31 5d 20 5b 48 31 32 39 37 33  [H12971] [H12973
2c720 5d 20 5b 48 31 32 39 37 35 5d 20 5b 48 31 32 39  ] [H12975] [H129
2c730 37 37 5d 20 5b 48 31 32 39 37 39 5d 20 5b 48 31  77] [H12979] [H1
2c740 32 39 38 31 5d 20 5b 48 31 32 39 38 33 5d 20 5b  2981] [H12983] [
2c750 48 31 32 39 38 36 5d 0a 2a 2f 0a 76 6f 69 64 20  H12986].*/.void 
2c760 2a 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  *sqlite3_update_
2c770 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a  hook(.  sqlite3*
2c780 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  , .  void(*)(voi
2c790 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f  d *,int ,char co
2c7a0 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74  nst *,char const
2c7b0 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34   *,sqlite3_int64
2c7c0 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f  ),.  void*.);../
2c7d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
2c7e0 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
2c7f0 20 53 68 61 72 65 64 20 50 61 67 65 72 20 43 61   Shared Pager Ca
2c800 63 68 65 20 7b 48 31 30 33 33 30 7d 20 3c 53 33  che {H10330} <S3
2c810 30 39 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0900>.** KEYWORD
2c820 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68 65  S: {shared cache
2c830 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
2c840 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
2c850 64 69 73 61 62 6c 65 73 20 74 68 65 20 73 68 61  disables the sha
2c860 72 69 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61  ring of the data
2c870 62 61 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e  base cache.** an
2c880 64 20 73 63 68 65 6d 61 20 64 61 74 61 20 73 74  d schema data st
2c890 72 75 63 74 75 72 65 73 20 62 65 74 77 65 65 6e  ructures between
2c8a0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2c8b0 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69  ction | connecti
2c8c0 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ons].** to the s
2c8d0 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 53 68  ame database. Sh
2c8e0 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64  aring is enabled
2c8f0 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
2c900 20 69 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20   is true.** and 
2c910 64 69 73 61 62 6c 65 64 20 69 66 20 74 68 65 20  disabled if the 
2c920 61 72 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73  argument is fals
2c930 65 2e 0a 2a 2a 0a 2a 2a 20 43 61 63 68 65 20 73  e..**.** Cache s
2c940 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c 65  haring is enable
2c950 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 66  d and disabled f
2c960 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72 6f  or an entire pro
2c970 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73  cess..** This is
2c980 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66 20   a change as of 
2c990 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2c9a0 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20 76  .5.0. In prior v
2c9b0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2c9c0 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77 61  e,.** sharing wa
2c9d0 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  s enabled or dis
2c9e0 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20 74  abled for each t
2c9f0 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c 79  hread separately
2ca00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 63 68  ..**.** The cach
2ca10 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73  e sharing mode s
2ca20 65 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72  et by this inter
2ca30 66 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c  face effects all
2ca40 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   subsequent.** c
2ca50 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2ca60 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2ca70 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
2ca80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  nd [sqlite3_open
2ca90 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69  16()]..** Existi
2caa0 6e 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ng database conn
2cab0 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  ections continue
2cac0 20 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67   use the sharing
2cad0 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61   mode.** that wa
2cae0 73 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74  s in effect at t
2caf0 68 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72  he time they wer
2cb00 65 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  e opened..**.** 
2cb10 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63  Virtual tables c
2cb20 61 6e 6e 6f 74 20 62 65 20 75 73 65 64 20 77 69  annot be used wi
2cb30 74 68 20 61 20 73 68 61 72 65 64 20 63 61 63 68  th a shared cach
2cb40 65 2e 20 20 57 68 65 6e 20 73 68 61 72 65 64 0a  e.  When shared.
2cb50 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
2cb60 6c 65 64 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  led, the [sqlite
2cb70 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
2cb80 29 5d 20 41 50 49 20 75 73 65 64 20 74 6f 20 72  )] API used to r
2cb90 65 67 69 73 74 65 72 0a 2a 2a 20 76 69 72 74 75  egister.** virtu
2cba0 61 6c 20 74 61 62 6c 65 73 20 77 69 6c 6c 20 61  al tables will a
2cbb0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 61 6e 20  lways return an 
2cbc0 65 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  error..**.** Thi
2cbd0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
2cbe0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66  s [SQLITE_OK] if
2cbf0 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61   shared cache wa
2cc00 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  s enabled or dis
2cc10 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73  abled.** success
2cc20 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f  fully.  An [erro
2cc30 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2cc40 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a  ned otherwise..*
2cc50 2a 0a 2a 2a 20 53 68 61 72 65 64 20 63 61 63 68  *.** Shared cach
2cc60 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
2cc70 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20 74 68   default. But th
2cc80 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  is might change 
2cc90 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72 65 6c  in.** future rel
2cca0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
2ccb0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
2ccc0 68 61 74 20 63 61 72 65 20 61 62 6f 75 74 20 73  hat care about s
2ccd0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 73  hared.** cache s
2cce0 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20 73 65  etting should se
2ccf0 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c 79 2e  t it explicitly.
2cd00 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a  .**.** See Also:
2cd10 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72 65 64    [SQLite Shared
2cd20 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a 2a 0a  -Cache Mode].**.
2cd30 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
2cd40 20 5b 48 31 30 33 33 31 5d 20 5b 48 31 30 33 33   [H10331] [H1033
2cd50 36 5d 20 5b 48 31 30 33 33 37 5d 20 5b 48 31 30  6] [H10337] [H10
2cd60 33 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  339].*/.int sqli
2cd70 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
2cd80 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
2cd90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
2cda0 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
2cdb0 65 61 70 20 4d 65 6d 6f 72 79 20 7b 48 31 37 33  eap Memory {H173
2cdc0 34 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a 0a  40} <S30220>.**.
2cdd0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
2cde0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
2cdf0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
2ce00 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74  ts to free N byt
2ce10 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65  es.** of heap me
2ce20 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61  mory by dealloca
2ce30 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  ting non-essenti
2ce40 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
2ce50 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79  tions.** held by
2ce60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69   the database li
2ce70 62 72 61 72 79 2e 20 7b 45 4e 44 7d 20 20 4d 65  brary. {END}  Me
2ce80 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63 61 63  mory used to cac
2ce90 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70  he database.** p
2cea0 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76 65 20  ages to improve 
2ceb0 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73 20 61  performance is a
2cec0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e 6f 6e  n example of non
2ced0 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72  -essential memor
2cee0 79 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  y..** sqlite3_re
2cef0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72  lease_memory() r
2cf00 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2cf10 72 20 6f 66 20 62 79 74 65 73 20 61 63 74 75 61  r of bytes actua
2cf20 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a 20 77 68  lly freed,.** wh
2cf30 69 63 68 20 6d 69 67 68 74 20 62 65 20 6d 6f 72  ich might be mor
2cf40 65 20 6f 72 20 6c 65 73 73 20 74 68 61 6e 20 74  e or less than t
2cf50 68 65 20 61 6d 6f 75 6e 74 20 72 65 71 75 65 73  he amount reques
2cf60 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ted..**.** Requi
2cf70 72 65 6d 65 6e 74 73 3a 20 5b 48 31 37 33 34 31  rements: [H17341
2cf80 5d 20 5b 48 31 37 33 34 32 5d 0a 2a 2f 0a 69 6e  ] [H17342].*/.in
2cf90 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  t sqlite3_releas
2cfa0 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a  e_memory(int);..
2cfb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2cfc0 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
2cfd0 6e 20 48 65 61 70 20 53 69 7a 65 20 7b 48 31 37  n Heap Size {H17
2cfe0 33 35 30 7d 20 3c 53 33 30 32 32 30 3e 0a 2a 2a  350} <S30220>.**
2cff0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2d000 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
2d010 29 20 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63  ) interface plac
2d020 65 73 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69  es a "soft" limi
2d030 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75  t.** on the amou
2d040 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72  nt of heap memor
2d050 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c  y that may be al
2d060 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
2d070 65 2e 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  e..** If an inte
2d080 72 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rnal allocation 
2d090 69 73 20 72 65 71 75 65 73 74 65 64 20 74 68 61  is requested tha
2d0a0 74 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74  t would exceed t
2d0b0 68 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70 20  he.** soft heap 
2d0c0 6c 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f  limit, [sqlite3_
2d0d0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
2d0e0 5d 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65  ] is invoked one
2d0f0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65   or.** more time
2d100 73 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d  s to free up som
2d110 65 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74  e space before t
2d120 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  he allocation is
2d130 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a   performed..**.*
2d140 2a 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63  * The limit is c
2d150 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65  alled "soft", be
2d160 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65  cause if [sqlite
2d170 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2d180 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72  ()].** cannot fr
2d190 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  ee sufficient me
2d1a0 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20  mory to prevent 
2d1b0 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62  the limit from b
2d1c0 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a  eing exceeded,.*
2d1d0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  * the memory is 
2d1e0 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79  allocated anyway
2d1f0 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74   and the current
2d200 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
2d210 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 6e 65 67  eds..**.** A neg
2d220 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76 61  ative or zero va
2d230 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73 20  lue for N means 
2d240 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e 6f  that there is no
2d250 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
2d260 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2d270 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
2d280 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65 20  )] will only be 
2d290 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d 6f  called when memo
2d2a0 72 79 20 69 73 20 65 78 68 61 75 73 74 65 64 2e  ry is exhausted.
2d2b0 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
2d2c0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 73 6f  value for the so
2d2d0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
2d2e0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   zero..**.** SQL
2d2f0 69 74 65 20 6d 61 6b 65 73 20 61 20 62 65 73 74  ite makes a best
2d300 20 65 66 66 6f 72 74 20 74 6f 20 68 6f 6e 6f 72   effort to honor
2d310 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2d320 69 6d 69 74 2e 0a 2a 2a 20 42 75 74 20 69 66 20  imit..** But if 
2d330 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2d340 6d 69 74 20 63 61 6e 6e 6f 74 20 62 65 20 68 6f  mit cannot be ho
2d350 6e 6f 72 65 64 2c 20 65 78 65 63 75 74 69 6f 6e  nored, execution
2d360 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 69 6e 75   will.** continu
2d370 65 20 77 69 74 68 6f 75 74 20 65 72 72 6f 72 20  e without error 
2d380 6f 72 20 6e 6f 74 69 66 69 63 61 74 69 6f 6e 2e  or notification.
2d390 20 20 54 68 69 73 20 69 73 20 77 68 79 20 74 68    This is why th
2d3a0 65 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20 63 61  e limit is.** ca
2d3b0 6c 6c 65 64 20 61 20 22 73 6f 66 74 22 20 6c 69  lled a "soft" li
2d3c0 6d 69 74 2e 20 20 49 74 20 69 73 20 61 64 76 69  mit.  It is advi
2d3d0 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  sory only..**.**
2d3e0 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
2d3f0 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
2d400 74 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  this routine onl
2d410 79 20 63 6f 6e 73 74 72 61 69 6e 65 64 20 74 68  y constrained th
2d420 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
2d430 63 61 74 65 64 20 62 79 20 61 20 73 69 6e 67 6c  cated by a singl
2d440 65 20 74 68 72 65 61 64 20 2d 20 74 68 65 20 73  e thread - the s
2d450 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
2d460 69 63 68 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ich this routine
2d470 0a 2a 2a 20 72 75 6e 73 2e 20 20 42 65 67 69 6e  .** runs.  Begin
2d480 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65  ning with SQLite
2d490 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2c 20   version 3.5.0, 
2d4a0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2d4b0 6d 69 74 20 69 73 0a 2a 2a 20 61 70 70 6c 69 65  mit is.** applie
2d4c0 64 20 74 6f 20 61 6c 6c 20 74 68 72 65 61 64 73  d to all threads
2d4d0 2e 20 54 68 65 20 76 61 6c 75 65 20 73 70 65 63  . The value spec
2d4e0 69 66 69 65 64 20 66 6f 72 20 74 68 65 20 73 6f  ified for the so
2d4f0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 0a 2a 2a  ft heap limit.**
2d500 20 69 73 20 61 6e 20 75 70 70 65 72 20 62 6f 75   is an upper bou
2d510 6e 64 20 6f 6e 20 74 68 65 20 74 6f 74 61 6c 20  nd on the total 
2d520 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2d530 6e 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 61 64  n for all thread
2d540 73 2e 20 49 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e  s. In.** version
2d550 20 33 2e 35 2e 30 20 74 68 65 72 65 20 69 73 20   3.5.0 there is 
2d560 6e 6f 20 6d 65 63 68 61 6e 69 73 6d 20 66 6f 72  no mechanism for
2d570 20 6c 69 6d 69 74 69 6e 67 20 74 68 65 20 68 65   limiting the he
2d580 61 70 20 75 73 61 67 65 20 66 6f 72 0a 2a 2a 20  ap usage for.** 
2d590 69 6e 64 69 76 69 64 75 61 6c 20 74 68 72 65 61  individual threa
2d5a0 64 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ds..**.** Requir
2d5b0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 33  ements:.** [H163
2d5c0 35 31 5d 20 5b 48 31 36 33 35 32 5d 20 5b 48 31  51] [H16352] [H1
2d5d0 36 33 35 33 5d 20 5b 48 31 36 33 35 34 5d 20 5b  6353] [H16354] [
2d5e0 48 31 36 33 35 35 5d 20 5b 48 31 36 33 35 38 5d  H16355] [H16358]
2d5f0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2d600 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
2d610 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
2d620 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20  PI3REF: Extract 
2d630 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41  Metadata About A
2d640 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62   Column Of A Tab
2d650 6c 65 20 7b 48 31 32 38 35 30 7d 20 3c 53 36 30  le {H12850} <S60
2d660 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  300>.**.** This 
2d670 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2d680 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61  metadata about a
2d690 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
2d6a0 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a   of a specific.*
2d6b0 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  * database table
2d6c0 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
2d6d0 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  g the [database 
2d6e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
2d6f0 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  le.** passed as 
2d700 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
2d710 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
2d720 2a 2a 20 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  ** The column is
2d730 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2d740 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
2d750 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
2d760 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69  meters to.** thi
2d770 73 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  s function. The 
2d780 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2d790 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
2d7a0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2d7b0 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
2d7c0 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72 20 61  in", "temp" or a
2d7d0 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
2d7e0 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
2d7f0 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
2d800 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
2d810 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74  If it is NULL, t
2d820 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65 64  hen all attached
2d830 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20 73   databases are s
2d840 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74  earched.** for t
2d850 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20 74  he table using t
2d860 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
2d870 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64 61  m used by the da
2d880 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74 6f  tabase engine to
2d890 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71 75  .** resolve unqu
2d8a0 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72 65  alified table re
2d8b0 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20  ferences..**.** 
2d8c0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2d8d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
2d8e0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
2d8f0 20 61 72 65 20 74 68 65 20 74 61 62 6c 65 20 61   are the table a
2d900 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d  nd column.** nam
2d910 65 20 6f 66 20 74 68 65 20 64 65 73 69 72 65 64  e of the desired
2d920 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74   column, respect
2d930 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f  ively. Neither o
2d940 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
2d950 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rs.** may be NUL
2d960 4c 2e 0a 2a 2a 0a 2a 2a 20 4d 65 74 61 64 61 74  L..**.** Metadat
2d970 61 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  a is returned by
2d980 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20   writing to the 
2d990 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73  memory locations
2d9a0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35   passed as the 5
2d9b0 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71  th.** and subseq
2d9c0 75 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20  uent parameters 
2d9d0 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  to this function
2d9e0 2e 20 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61  . Any of these a
2d9f0 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a  rguments may be.
2da00 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63  ** NULL, in whic
2da10 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65  h case the corre
2da20 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74  sponding element
2da30 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20   of metadata is 
2da40 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  omitted..**.** <
2da50 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
2da60 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
2da70 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61  >.** <tr><th> Pa
2da80 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74  rameter <th> Out
2da90 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  put<br>Type <th>
2daa0 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a    Description.**
2dab0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68  .** <tr><td> 5th
2dac0 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72   <td> const char
2dad0 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65  * <td> Data type
2dae0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68  .** <tr><td> 6th
2daf0 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72   <td> const char
2db00 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64  * <td> Name of d
2db10 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e  efault collation
2db20 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72   sequence.** <tr
2db30 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69  ><td> 7th <td> i
2db40 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20  nt         <td> 
2db50 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68  True if column h
2db60 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  as a NOT NULL co
2db70 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e  nstraint.** <tr>
2db80 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e  <td> 8th <td> in
2db90 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
2dba0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
2dbb0 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49   part of the PRI
2dbc0 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e  MARY KEY.** <tr>
2dbd0 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e  <td> 9th <td> in
2dbe0 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
2dbf0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
2dc00 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d   [AUTOINCREMENT]
2dc10 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
2dc20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
2dc30 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72 79 20 70  .** The memory p
2dc40 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
2dc50 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74   character point
2dc60 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72  ers returned for
2dc70 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74   the.** declarat
2dc80 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c  ion type and col
2dc90 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2dca0 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e  is valid only un
2dcb0 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
2dcc0 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69  call to any SQLi
2dcd0 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e  te API function.
2dce0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70  .**.** If the sp
2dcf0 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69 73  ecified table is
2dd00 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65 77   actually a view
2dd10 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  , an [error code
2dd20 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
2dd30 2a 0a 2a 2a 20 49 66 20 74 68 65 20 73 70 65 63  *.** If the spec
2dd40 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20  ified column is 
2dd50 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f  "rowid", "oid" o
2dd60 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20  r "_rowid_" and 
2dd70 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50  an.** [INTEGER P
2dd80 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
2dd90 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c  mn has been expl
2dda0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c  icitly declared,
2ddb0 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74   then the output
2ddc0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61  .** parameters a
2ddd0 72 65 20 73 65 74 20 66 6f 72 20 74 68 65 20 65  re set for the e
2dde0 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
2ddf0 65 64 20 63 6f 6c 75 6d 6e 2e 20 49 66 20 74 68  ed column. If th
2de00 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
2de10 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2de20 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2de30 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74  Y KEY] column, t
2de40 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
2de50 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
2de60 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   set as follows:
2de70 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
2de80 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
2de90 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
2dea0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2deb0 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
2dec0 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
2ded0 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
2dee0 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
2def0 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
2df00 2a 20 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 54  * </pre>.**.** T
2df10 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
2df20 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72   load one or mor
2df30 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20 64  e schemas from d
2df40 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20 49  atabase files. I
2df50 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63  f an.** error oc
2df60 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69 73  curs during this
2df70 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
2df80 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74 61  the requested ta
2df90 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  ble or column.**
2dfa0 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64   cannot be found
2dfb0 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  , an [error code
2dfc0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
2dfd0 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  d an error messa
2dfe0 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68  ge left.** in th
2dff0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2e000 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72  ection] (to be r
2e010 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20 73  etrieved using s
2e020 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 29  qlite3_errmsg())
2e030 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50 49  ..**.** This API
2e040 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
2e050 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
2e060 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
2e070 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
2e080 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
2e090 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
2e0a0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
2e0b0 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74   defined..*/.int
2e0c0 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63   sqlite3_table_c
2e0d0 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a  olumn_metadata(.
2e0e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2e0f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e100 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   Connection hand
2e110 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2e120 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
2e130 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2e140 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a  name or NULL */.
2e150 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
2e160 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a  ableName,     /*
2e170 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20   Table name */. 
2e180 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
2e190 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20  lumnName,    /* 
2e1a0 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20  Column name */. 
2e1b0 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
2e1c0 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20  DataType,    /* 
2e1d0 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64  OUTPUT: Declared
2e1e0 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20   data type */.  
2e1f0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43  char const **pzC
2e200 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f  ollSeq,     /* O
2e210 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e  UTPUT: Collation
2e220 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a   sequence name *
2e230 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c  /.  int *pNotNul
2e240 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
2e250 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
2e260 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73  if NOT NULL cons
2e270 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f  traint exists */
2e280 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79  .  int *pPrimary
2e290 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Key,           /
2e2a0 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
2e2b0 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66  f column part of
2e2c0 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41   PK */.  int *pA
2e2d0 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20  utoinc          
2e2e0 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2e2f0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
2e300 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74  s auto-increment
2e310 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2e320 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20  PI3REF: Load An 
2e330 45 78 74 65 6e 73 69 6f 6e 20 7b 48 31 32 36 30  Extension {H1260
2e340 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a  0} <S20500>.**.*
2e350 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
2e360 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65   loads an SQLite
2e370 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
2e380 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65  ry from the name
2e390 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48  d file..**.** {H
2e3a0 31 32 36 30 31 7d 20 54 68 65 20 73 71 6c 69 74  12601} The sqlit
2e3b0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2e3c0 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  n() interface at
2e3d0 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61  tempts to load a
2e3e0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 53 51  n.**          SQ
2e3f0 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
2e400 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
2e410 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69   in the file zFi
2e420 6c 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30  le..**.** {H1260
2e430 32 7d 20 54 68 65 20 65 6e 74 72 79 20 70 6f 69  2} The entry poi
2e440 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 0a  nt is zProc..**.
2e450 2a 2a 20 7b 48 31 32 36 30 33 7d 20 7a 50 72 6f  ** {H12603} zPro
2e460 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77  c may be 0, in w
2e470 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61  hich case the na
2e480 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20  me of the entry 
2e490 70 6f 69 6e 74 0a 2a 2a 20 20 20 20 20 20 20 20  point.**        
2e4a0 20 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73    defaults to "s
2e4b0 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e  qlite3_extension
2e4c0 5f 69 6e 69 74 22 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _init"..**.** {H
2e4d0 31 32 36 30 34 7d 20 54 68 65 20 73 71 6c 69 74  12604} The sqlit
2e4e0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2e4f0 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68  n() interface sh
2e500 61 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 20 20  all return.**   
2e510 20 20 20 20 20 20 20 5b 53 51 4c 49 54 45 5f 4f         [SQLITE_O
2e520 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
2e530 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2e540 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f   if something go
2e550 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 0a 2a 2a 20  es wrong..**.** 
2e560 7b 48 31 32 36 30 35 7d 20 49 66 20 61 6e 20 65  {H12605} If an e
2e570 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
2e580 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
2e590 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 20  0, then the.**  
2e5a0 20 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33          [sqlite3
2e5b0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2e5c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
2e5d0 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  ll attempt to.**
2e5e0 20 20 20 20 20 20 20 20 20 20 66 69 6c 6c 20 2a            fill *
2e5f0 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72  pzErrMsg with er
2e600 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
2e610 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72   stored in memor
2e620 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f 62  y.**          ob
2e630 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2e640 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
2e650 7b 45 4e 44 7d 20 20 54 68 65 20 63 61 6c 6c 69  {END}  The calli
2e660 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 20  ng function.**  
2e670 20 20 20 20 20 20 20 20 73 68 6f 75 6c 64 20 66          should f
2e680 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20  ree this memory 
2e690 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2e6a0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
2e6b0 2a 2a 20 7b 48 31 32 36 30 36 7d 20 45 78 74 65  ** {H12606} Exte
2e6c0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75  nsion loading mu
2e6d0 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73  st be enabled us
2e6e0 69 6e 67 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ing.**          
2e6f0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
2e700 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2e710 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ] prior to calli
2e720 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20  ng this API,.** 
2e730 20 20 20 20 20 20 20 20 20 6f 74 68 65 72 77 69           otherwi
2e740 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c  se an error will
2e750 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2f   be returned..*/
2e760 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61  .int sqlite3_loa
2e770 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73  d_extension(.  s
2e780 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2e790 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65       /* Load the
2e7a0 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20   extension into 
2e7b0 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63 6f  this database co
2e7c0 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f  nnection */.  co
2e7d0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
2e7e0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
2e7f0 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61 72  he shared librar
2e800 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74  y containing ext
2e810 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73  ension */.  cons
2e820 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20  t char *zProc,  
2e830 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74    /* Entry point
2e840 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d 20  .  Derived from 
2e850 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20  zFile if 0 */.  
2e860 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20  char **pzErrMsg 
2e870 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72 72        /* Put err
2e880 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65 20  or message here 
2e890 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a  if not 0 */.);..
2e8a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e8b0 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c  Enable Or Disabl
2e8c0 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64  e Extension Load
2e8d0 69 6e 67 20 7b 48 31 32 36 32 30 7d 20 3c 53 32  ing {H12620} <S2
2e8e0 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 53 6f 20 61  0500>.**.** So a
2e8f0 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65  s not to open se
2e900 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20  curity holes in 
2e910 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f  older applicatio
2e920 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75  ns that are.** u
2e930 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61  nprepared to dea
2e940 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e  l with extension
2e950 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73   loading, and as
2e960 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61   a means of disa
2e970 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69  bling.** extensi
2e980 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65  on loading while
2e990 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72   evaluating user
2e9a0 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68  -entered SQL, th
2e9b0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a  e following API.
2e9c0 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  ** is provided t
2e9d0 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  o turn the [sqli
2e9e0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
2e9f0 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20  on()] mechanism 
2ea00 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a  on and off..**.*
2ea10 2a 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * Extension load
2ea20 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64 65  ing is off by de
2ea30 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b 65  fault. See ticke
2ea40 74 20 23 31 38 36 33 2e 0a 2a 2a 0a 2a 2a 20 7b  t #1863..**.** {
2ea50 48 31 32 36 32 31 7d 20 43 61 6c 6c 20 74 68 65  H12621} Call the
2ea60 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
2ea70 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2ea80 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e   routine with on
2ea90 6f 66 66 3d 3d 31 0a 2a 2a 20 20 20 20 20 20 20  off==1.**       
2eaa0 20 20 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e     to turn exten
2eab0 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20  sion loading on 
2eac0 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68  and call it with
2ead0 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72   onoff==0 to tur
2eae0 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 74  n.**          it
2eaf0 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e   back off again.
2eb00 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 32 32 7d 20  .**.** {H12622} 
2eb10 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  Extension loadin
2eb20 67 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61  g is off by defa
2eb30 75 6c 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ult..*/.int sqli
2eb40 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
2eb50 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65  extension(sqlite
2eb60 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66  3 *db, int onoff
2eb70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2eb80 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c  EF: Automaticall
2eb90 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  y Load An Extens
2eba0 69 6f 6e 73 20 7b 48 31 32 36 34 30 7d 20 3c 53  ions {H12640} <S
2ebb0 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  20500>.**.** Thi
2ebc0 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76  s API can be inv
2ebd0 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20  oked at program 
2ebe0 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72  startup in order
2ebf0 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20   to register.** 
2ec00 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74  one or more stat
2ec10 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78  ically linked ex
2ec20 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69  tensions that wi
2ec30 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a  ll be available.
2ec40 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64  ** to all new [d
2ec50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ec60 6f 6e 73 5d 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  ons]. {END}.**.*
2ec70 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73  * This routine s
2ec80 74 6f 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20  tores a pointer 
2ec90 74 6f 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  to the extension
2eca0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 74 68 61   in an array tha
2ecb0 74 20 69 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  t is.** obtained
2ecc0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2ecd0 61 6c 6c 6f 63 28 29 5d 2e 20 20 49 66 20 79 6f  alloc()].  If yo
2ece0 75 20 72 75 6e 20 61 20 6d 65 6d 6f 72 79 20 6c  u run a memory l
2ecf0 65 61 6b 20 63 68 65 63 6b 65 72 0a 2a 2a 20 6f  eak checker.** o
2ed00 6e 20 79 6f 75 72 20 70 72 6f 67 72 61 6d 20 61  n your program a
2ed10 6e 64 20 69 74 20 72 65 70 6f 72 74 73 20 61 20  nd it reports a 
2ed20 6c 65 61 6b 20 62 65 63 61 75 73 65 20 6f 66 20  leak because of 
2ed30 74 68 69 73 20 61 72 72 61 79 2c 20 69 6e 76 6f  this array, invo
2ed40 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ke.** [sqlite3_r
2ed50 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
2ed60 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20  ion()] prior to 
2ed70 73 68 75 74 64 6f 77 6e 20 74 6f 20 66 72 65 65  shutdown to free
2ed80 20 74 68 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 0a   the memory..**.
2ed90 2a 2a 20 7b 48 31 32 36 34 31 7d 20 54 68 69 73  ** {H12641} This
2eda0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
2edb0 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e  ers an extension
2edc0 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61   entry point tha
2edd0 74 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20  t is.**         
2ede0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
2edf0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2ee00 61 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20  a new [database 
2ee10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 20  connection].**  
2ee20 20 20 20 20 20 20 20 20 69 73 20 6f 70 65 6e 65          is opene
2ee30 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
2ee40 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2ee50 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
2ee60 20 20 20 20 20 20 20 20 20 20 6f 72 20 5b 73 71            or [sq
2ee70 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
2ee80 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 32 7d  ..**.** {H12642}
2ee90 20 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e   Duplicate exten
2eea0 73 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74  sions are detect
2eeb0 65 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68  ed so calling th
2eec0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 20 20  is routine.**   
2eed0 20 20 20 20 20 20 20 6d 75 6c 74 69 70 6c 65 20         multiple 
2eee0 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
2eef0 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73  ame extension is
2ef00 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 0a 2a 2a   harmless..**.**
2ef10 20 7b 48 31 32 36 34 33 7d 20 54 68 69 73 20 72   {H12643} This r
2ef20 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20  outine stores a 
2ef30 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65  pointer to the e
2ef40 78 74 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61  xtension in an a
2ef50 72 72 61 79 0a 2a 2a 20 20 20 20 20 20 20 20 20  rray.**         
2ef60 20 74 68 61 74 20 69 73 20 6f 62 74 61 69 6e 65   that is obtaine
2ef70 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2ef80 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 0a 2a 2a  malloc()]..**.**
2ef90 20 7b 48 31 32 36 34 34 7d 20 41 75 74 6f 6d 61   {H12644} Automa
2efa0 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 61  tic extensions a
2efb0 70 70 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  pply across all 
2efc0 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 69 6e 74 20  threads..*/.int 
2efd0 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
2efe0 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45  ension(void (*xE
2eff0 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69 64 29  ntryPoint)(void)
2f000 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f010 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f 6d 61  EF: Reset Automa
2f020 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  tic Extension Lo
2f030 61 64 69 6e 67 20 7b 48 31 32 36 36 30 7d 20 3c  ading {H12660} <
2f040 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68  S20500>.**.** Th
2f050 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61  is function disa
2f060 62 6c 65 73 20 61 6c 6c 20 70 72 65 76 69 6f 75  bles all previou
2f070 73 6c 79 20 72 65 67 69 73 74 65 72 65 64 20 61  sly registered a
2f080 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 65 78 74 65  utomatic.** exte
2f090 6e 73 69 6f 6e 73 2e 20 7b 45 4e 44 7d 20 20 49  nsions. {END}  I
2f0a0 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66  t undoes the eff
2f0b0 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72  ect of all prior
2f0c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75 74  .** [sqlite3_aut
2f0d0 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63  o_extension()] c
2f0e0 61 6c 6c 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32  alls..**.** {H12
2f0f0 36 36 31 7d 20 54 68 69 73 20 66 75 6e 63 74 69  661} This functi
2f100 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20  on disables all 
2f110 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73  previously regis
2f120 74 65 72 65 64 0a 2a 2a 20 20 20 20 20 20 20 20  tered.**        
2f130 20 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74 65    automatic exte
2f140 6e 73 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  nsions..**.** {H
2f150 31 32 36 36 32 7d 20 54 68 69 73 20 66 75 6e 63  12662} This func
2f160 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 75  tion disables au
2f170 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
2f180 6e 73 20 69 6e 20 61 6c 6c 20 74 68 72 65 61 64  ns in all thread
2f190 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  s..*/.void sqlit
2f1a0 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78  e3_reset_auto_ex
2f1b0 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a  tension(void);..
2f1c0 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49  /*.****** EXPERI
2f1d0 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74  MENTAL - subject
2f1e0 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f   to change witho
2f1f0 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a  ut notice ******
2f200 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54  ********.**.** T
2f210 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
2f220 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
2f230 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63  e mechanism is c
2f240 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
2f250 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
2f260 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
2f270 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
2f280 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
2f290 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
2f2a0 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
2f2b0 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
2f2c0 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
2f2d0 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
2f2e0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
2f2f0 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
2f300 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
2f310 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
2f320 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
2f330 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
2f340 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
2f350 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
2f360 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
2f370 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75  ..*/../*.** Stru
2f380 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74  ctures used by t
2f390 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
2f3a0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79   interface.*/.ty
2f3b0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2f3c0 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65  ite3_vtab sqlite
2f3d0 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20  3_vtab;.typedef 
2f3e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
2f3f0 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65  ndex_info sqlite
2f400 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79  3_index_info;.ty
2f410 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2f420 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2f430 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
2f440 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74  rsor;.typedef st
2f450 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
2f460 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ule sqlite3_modu
2f470 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  le;../*.** CAPI3
2f480 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
2f490 6c 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 30  le Object {H1800
2f4a0 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b  0} <S20400>.** K
2f4b0 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
2f4c0 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c  _module {virtual
2f4d0 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a   table module}.*
2f4e0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
2f4f0 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74  *.** This struct
2f500 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63  ure, sometimes c
2f510 61 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75  alled a a "virtu
2f520 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22  al table module"
2f530 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68  , .** defines th
2f540 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
2f550 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74   of a [virtual t
2f560 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69  ables].  .** Thi
2f570 73 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73  s structure cons
2f580 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d  ists mostly of m
2f590 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
2f5a0 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 41 20 76  odule..**.** A v
2f5b0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
2f5c0 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62  ule is created b
2f5d0 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70  y filling in a p
2f5e0 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73  ersistent.** ins
2f5f0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
2f600 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73  ructure and pass
2f610 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ing a pointer to
2f620 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a   that instance.*
2f630 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
2f640 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f  eate_module()] o
2f650 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
2f660 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a  e_module_v2()]..
2f670 2a 2a 20 54 68 65 20 72 65 67 69 73 74 72 61 74  ** The registrat
2f680 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69  ion remains vali
2f690 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65  d until it is re
2f6a0 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66  placed by a diff
2f6b0 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20  erent.** module 
2f6c0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61  or until the [da
2f6d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f6e0 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20  n] closes.  The 
2f6f0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  content.** of th
2f700 69 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  is structure mus
2f710 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69  t not change whi
2f720 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65  le it is registe
2f730 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20  red with.** any 
2f740 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f750 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ion..*/.struct s
2f760 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a  qlite3_module {.
2f770 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
2f780 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29    int (*xCreate)
2f790 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
2f7a0 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
2f7b0 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
2f7c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
2f7d0 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
2f7e0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
2f7f0 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
2f800 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
2f810 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  Connect)(sqlite3
2f820 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
2f830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
2f840 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
2f850 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
2f860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
2f870 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
2f880 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
2f890 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65   int (*xBestInde
2f8a0 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  x)(sqlite3_vtab 
2f8b0 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
2f8c0 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20  index_info*);.  
2f8d0 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63  int (*xDisconnec
2f8e0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
2f8f0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
2f900 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74  *xDestroy)(sqlit
2f910 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
2f920 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
2f930 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
2f940 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61  Tab, sqlite3_vta
2f950 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72  b_cursor **ppCur
2f960 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sor);.  int (*xC
2f970 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74  lose)(sqlite3_vt
2f980 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
2f990 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71  nt (*xFilter)(sq
2f9a0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2f9b0 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20  r*, int idxNum, 
2f9c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53  const char *idxS
2f9d0 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  tr,.            
2f9e0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71      int argc, sq
2f9f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72  lite3_value **ar
2fa00 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65  gv);.  int (*xNe
2fa10 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  xt)(sqlite3_vtab
2fa20 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
2fa30 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33   (*xEof)(sqlite3
2fa40 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
2fa50 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29    int (*xColumn)
2fa60 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
2fa70 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63  rsor*, sqlite3_c
2fa80 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20  ontext*, int);. 
2fa90 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73   int (*xRowid)(s
2faa0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2fab0 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  or*, sqlite3_int
2fac0 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69  64 *pRowid);.  i
2fad0 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71  nt (*xUpdate)(sq
2fae0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e  lite3_vtab *, in
2faf0 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  t, sqlite3_value
2fb00 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74   **, sqlite3_int
2fb10 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  64 *);.  int (*x
2fb20 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76  Begin)(sqlite3_v
2fb30 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
2fb40 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
2fb50 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
2fb60 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69  ;.  int (*xCommi
2fb70 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
2fb80 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
2fb90 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69  *xRollback)(sqli
2fba0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
2fbb0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46  ;.  int (*xFindF
2fbc0 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33  unction)(sqlite3
2fbd0 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e  _vtab *pVtab, in
2fbe0 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68  t nArg, const ch
2fbf0 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20  ar *zName,.     
2fc00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fc10 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63    void (**pxFunc
2fc20 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2fc30 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2fc40 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20  alue**),.       
2fc50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fc60 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20  void **ppArg);. 
2fc70 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28   int (*xRename)(
2fc80 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
2fc90 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  tab, const char 
2fca0 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  *zNew);.};../*.*
2fcb0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
2fcc0 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69  ual Table Indexi
2fcd0 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 7b  ng Information {
2fce0 48 31 38 31 30 30 7d 20 3c 53 32 30 34 30 30 3e  H18100} <S20400>
2fcf0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
2fd00 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
2fd10 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
2fd20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2fd30 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74  e3_index_info st
2fd40 72 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20  ructure and its 
2fd50 73 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73  substructures is
2fd60 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73   used to.** pass
2fd70 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74   information int
2fd80 6f 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68  o and receive th
2fd90 65 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65  e reply from the
2fda0 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a   [xBestIndex].**
2fdb0 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69   method of a [vi
2fdc0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
2fdd0 6c 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73  le].  The fields
2fde0 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a   under **Inputs*
2fdf0 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70  * are the.** inp
2fe00 75 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65  uts to xBestInde
2fe10 78 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f  x and are read-o
2fe20 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78  nly.  xBestIndex
2fe30 20 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20   inserts its.** 
2fe40 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65  results into the
2fe50 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65   **Outputs** fie
2fe60 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  lds..**.** The a
2fe70 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
2fe80 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45  ay records WHERE
2fe90 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
2fea0 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a  nts of the form:
2feb0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75  .**.** <pre>colu
2fec0 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e  mn OP expr</pre>
2fed0 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20  .**.** where OP 
2fee0 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b  is =, &lt;, &lt;
2fef0 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b  =, &gt;, or &gt;
2ff00 3d 2e 20 20 54 68 65 20 70 61 72 74 69 63 75 6c  =.  The particul
2ff10 61 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a  ar operator is.*
2ff20 2a 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e  * stored in aCon
2ff30 73 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 54  straint[].op.  T
2ff40 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2ff50 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64  column is stored
2ff60 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69   in.** aConstrai
2ff70 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 61  nt[].iColumn.  a
2ff80 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61  Constraint[].usa
2ff90 62 6c 65 20 69 73 20 54 52 55 45 20 69 66 20 74  ble is TRUE if t
2ffa0 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68  he.** expr on th
2ffb0 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64  e right-hand sid
2ffc0 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75 61 74  e can be evaluat
2ffd0 65 64 20 28 61 6e 64 20 74 68 75 73 20 74 68 65  ed (and thus the
2ffe0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69   constraint.** i
2fff0 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20 66 61  s usable) and fa
30000 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e 6f 74  lse if it cannot
30010 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 70 74 69  ..**.** The opti
30020 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61  mizer automatica
30030 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d  lly inverts term
30040 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65  s of the form "e
30050 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a  xpr OP column".*
30060 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65  * and makes othe
30070 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e  r simplification
30080 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63  s to the WHERE c
30090 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65  lause in an atte
300a0 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73  mpt to.** get as
300b0 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75   many WHERE clau
300c0 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68  se terms into th
300d0 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f  e form shown abo
300e0 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a  ve as possible..
300f0 2a 2a 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69  ** The aConstrai
30100 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
30110 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
30120 61 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68  ause terms in th
30130 65 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72  e correct.** for
30140 6d 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20  m that refer to 
30150 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76  the particular v
30160 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69  irtual table bei
30170 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a  ng queried..**.*
30180 2a 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  * Information ab
30190 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59  out the ORDER BY
301a0 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65   clause is store
301b0 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e  d in aOrderBy[].
301c0 0a 2a 2a 20 45 61 63 68 20 74 65 72 6d 20 6f 66  .** Each term of
301d0 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64   aOrderBy record
301e0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  s a column of th
301f0 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73  e ORDER BY claus
30200 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42  e..**.** The [xB
30210 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64  estIndex] method
30220 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73   must fill aCons
30230 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69  traintUsage[] wi
30240 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  th information.*
30250 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72  * about what par
30260 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20  ameters to pass 
30270 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 49 66 20  to xFilter.  If 
30280 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e  argvIndex>0 then
30290 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61  .** the right-ha
302a0 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63  nd side of the c
302b0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f  orresponding aCo
302c0 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76  nstraint[] is ev
302d0 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62  aluated.** and b
302e0 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49  ecomes the argvI
302f0 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e  ndex-th entry in
30300 20 61 72 67 76 2e 20 20 49 66 20 61 43 6f 6e 73   argv.  If aCons
30310 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d  traintUsage[].om
30320 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74  it.** is true, t
30330 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hen the constrai
30340 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f  nt is assumed to
30350 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65   be fully handle
30360 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74  d by the.** virt
30370 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73  ual table and is
30380 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61   not checked aga
30390 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  in by SQLite..**
303a0 0a 2a 2a 20 54 68 65 20 69 64 78 4e 75 6d 20 61  .** The idxNum a
303b0 6e 64 20 69 64 78 50 74 72 20 76 61 6c 75 65 73  nd idxPtr values
303c0 20 61 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e   are recorded an
303d0 64 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  d passed into th
303e0 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d  e.** [xFilter] m
303f0 65 74 68 6f 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74  ethod..** [sqlit
30400 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73  e3_free()] is us
30410 65 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74  ed to free idxPt
30420 72 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  r if and only if
30430 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49  f.** needToFreeI
30440 64 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a  dxPtr is true..*
30450 2a 0a 2a 2a 20 54 68 65 20 6f 72 64 65 72 42 79  *.** The orderBy
30460 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74  Consumed means t
30470 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20  hat output from 
30480 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74  [xFilter]/[xNext
30490 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a  ] will occur in.
304a0 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f  ** the correct o
304b0 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20  rder to satisfy 
304c0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
304d0 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73  use so that no s
304e0 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69  eparate.** sorti
304f0 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69  ng step is requi
30500 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 65  red..**.** The e
30510 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c  stimatedCost val
30520 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74  ue is an estimat
30530 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66  e of the cost of
30540 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61   doing the.** pa
30550 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e  rticular lookup.
30560 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66    A full scan of
30570 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20   a table with N 
30580 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68  entries should h
30590 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66  ave.** a cost of
305a0 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65   N.  A binary se
305b0 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20  arch of a table 
305c0 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f  of N entries sho
305d0 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f  uld have a.** co
305e0 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74  st of approximat
305f0 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73  ely log(N)..*/.s
30600 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
30610 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20  dex_info {.  /* 
30620 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20  Inputs */.  int 
30630 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  nConstraint;    
30640 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
30650 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61   of entries in a
30660 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  Constraint */.  
30670 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
30680 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20  ndex_constraint 
30690 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75  {.     int iColu
306a0 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  mn;             
306b0 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65   /* Column on le
306c0 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
306d0 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
306e0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
306f0 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20   op;         /* 
30700 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61  Constraint opera
30710 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  tor */.     unsi
30720 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c 65  gned char usable
30730 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66  ;     /* True if
30740 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74   this constraint
30750 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20   is usable */.  
30760 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73     int iTermOffs
30770 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  et;          /* 
30780 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  Used internally 
30790 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f  - xBestIndex sho
307a0 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20  uld ignore */.  
307b0 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20  } *aConstraint; 
307c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61             /* Ta
307d0 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61  ble of WHERE cla
307e0 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
307f0 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42  */.  int nOrderB
30800 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  y;              
30810 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72  /* Number of ter
30820 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20  ms in the ORDER 
30830 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73  BY clause */.  s
30840 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
30850 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20  dex_orderby {.  
30860 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
30870 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
30880 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f  Column number */
30890 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
308a0 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20 20  har desc;       
308b0 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53 43  /* True for DESC
308c0 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43  .  False for ASC
308d0 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72  . */.  } *aOrder
308e0 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  By;             
308f0 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42    /* The ORDER B
30900 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a  Y clause */.  /*
30910 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74   Outputs */.  st
30920 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
30930 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73  ex_constraint_us
30940 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72  age {.    int ar
30950 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20  gvIndex;        
30960 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e     /* if >0, con
30970 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74 20  straint is part 
30980 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74  of argv to xFilt
30990 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e  er */.    unsign
309a0 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20  ed char omit;   
309b0 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64     /* Do not cod
309c0 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68 69  e a test for thi
309d0 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a  s constraint */.
309e0 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74    } *aConstraint
309f0 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78  Usage;.  int idx
30a00 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20  Num;            
30a10 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73      /* Number us
30a20 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74  ed to identify t
30a30 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68  he index */.  ch
30a40 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20  ar *idxStr;     
30a50 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69           /* Stri
30a60 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74  ng, possibly obt
30a70 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
30a80 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69  e3_malloc */.  i
30a90 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78  nt needToFreeIdx
30aa0 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65  Str;      /* Fre
30ab0 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20 73  e idxStr using s
30ac0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 66  qlite3_free() if
30ad0 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f   true */.  int o
30ae0 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20  rderByConsumed; 
30af0 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66        /* True if
30b00 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65 61   output is alrea
30b10 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20  dy ordered */.  
30b20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64  double estimated
30b30 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73  Cost;      /* Es
30b40 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20  timated cost of 
30b50 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78  using this index
30b60 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53   */.};.#define S
30b70 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
30b80 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23  TRAINT_EQ    2.#
30b90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
30ba0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
30bb0 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53  T    4.#define S
30bc0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
30bd0 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23  TRAINT_LE    8.#
30be0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
30bf0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
30c00 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20  T    16.#define 
30c10 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
30c20 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32  STRAINT_GE    32
30c30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30c40 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
30c50 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a  _MATCH 64../*.**
30c60 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
30c70 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  ter A Virtual Ta
30c80 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  ble Implementati
30c90 6f 6e 20 7b 48 31 38 32 30 30 7d 20 3c 53 32 30  on {H18200} <S20
30ca0 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45  400>.** EXPERIME
30cb0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  NTAL.**.** This 
30cc0 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20  routine is used 
30cd0 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65  to register a ne
30ce0 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  w [virtual table
30cf0 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a   module] name..*
30d00 2a 20 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d  * Module names m
30d10 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65  ust be registere
30d20 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61  d before.** crea
30d30 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74  ting a new [virt
30d40 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67  ual table] using
30d50 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20   the module, or 
30d60 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a  before using a.*
30d70 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76  * preexisting [v
30d80 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f  irtual table] fo
30d90 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  r the module..**
30da0 0a 2a 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 6e  .** The module n
30db0 61 6d 65 20 69 73 20 72 65 67 69 73 74 65 72 65  ame is registere
30dc0 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  d on the [databa
30dd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
30de0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
30df0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
30e00 65 72 2e 20 20 54 68 65 20 6e 61 6d 65 20 6f 66  er.  The name of
30e10 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67   the module is g
30e20 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20  iven by the .** 
30e30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
30e40 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
30e50 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
30e60 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d  ter to.** the im
30e70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
30e80 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
30e90 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 54 68  le module].   Th
30ea0 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61  e fourth.** para
30eb0 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
30ec0 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61 74  trary client dat
30ed0 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
30ee0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
30ef0 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78 43  .** into the [xC
30f00 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e  reate] and [xCon
30f10 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66  nect] methods of
30f20 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62   the virtual tab
30f30 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65  le module.** whe
30f40 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c 20  n a new virtual 
30f50 74 61 62 6c 65 20 69 73 20 62 65 20 62 65 69 6e  table is be bein
30f60 67 20 63 72 65 61 74 65 64 20 6f 72 20 72 65 69  g created or rei
30f70 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a  nitialized..**.*
30f80 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
30f90 20 68 61 73 20 65 78 61 63 74 6c 79 20 74 68 65   has exactly the
30fa0 20 73 61 6d 65 20 65 66 66 65 63 74 20 61 73 20   same effect as 
30fb0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  calling.** [sqli
30fc0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
30fd0 65 5f 76 32 28 29 5d 20 77 69 74 68 20 61 20 4e  e_v2()] with a N
30fe0 55 4c 4c 20 63 6c 69 65 6e 74 20 64 61 74 61 20  ULL client data 
30ff0 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53  destructor..*/.S
31000 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
31010 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  AL int sqlite3_c
31020 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20  reate_module(.  
31030 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
31040 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
31050 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
31060 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
31070 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
31080 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
31090 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
310a0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
310b0 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
310c0 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a  _module *p,   /*
310d0 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
310e0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
310f0 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20  d *pClientData  
31100 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
31110 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
31120 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29  te/xConnect */.)
31130 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31140 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 56 69  F: Register A Vi
31150 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c  rtual Table Impl
31160 65 6d 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32  ementation {H182
31170 31 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20  10} <S20400>.** 
31180 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
31190 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
311a0 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
311b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
311c0 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6d 65  ate_module()] me
311d0 74 68 6f 64 2c 0a 2a 2a 20 65 78 63 65 70 74 20  thod,.** except 
311e0 74 68 61 74 20 69 74 20 68 61 73 20 61 6e 20 65  that it has an e
311f0 78 74 72 61 20 70 61 72 61 6d 65 74 65 72 20 74  xtra parameter t
31200 6f 20 73 70 65 63 69 66 79 20 0a 2a 2a 20 61 20  o specify .** a 
31210 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
31220 69 6f 6e 20 66 6f 72 20 74 68 65 20 63 6c 69 65  ion for the clie
31230 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  nt data pointer.
31240 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
31250 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
31260 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
31270 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  (if it is not NU
31280 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a  LL) when SQLite.
31290 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65  ** no longer nee
312a0 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61  ds the pClientDa
312b0 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 0a 2a 2f  ta pointer.  .*/
312c0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
312d0 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
312e0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
312f0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
31300 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
31310 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63  /* SQLite connec
31320 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72  tion to register
31330 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a   module with */.
31340 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
31350 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ame,         /* 
31360 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  Name of the modu
31370 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71  le */.  const sq
31380 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c  lite3_module *p,
31390 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
313a0 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
313b0 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44    void *pClientD
313c0 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ata,         /* 
313d0 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
313e0 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
313f0 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73   */.  void(*xDes
31400 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20  troy)(void*)    
31410 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72   /* Module destr
31420 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a  uctor function *
31430 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
31440 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
31450 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a  ble Instance Obj
31460 65 63 74 20 7b 48 31 38 30 31 30 7d 20 3c 53 32  ect {H18010} <S2
31470 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44  0400>.** KEYWORD
31480 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a  S: sqlite3_vtab.
31490 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
314a0 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
314b0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
314c0 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
314d0 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
314e0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 66 6f 6c 6c  s.** of the foll
314f0 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20  owing structure 
31500 74 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61  to describe a pa
31510 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63  rticular instanc
31520 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72  e.** of the [vir
31530 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61  tual table].  Ea
31540 63 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c  ch subclass will
31550 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20  .** be tailored 
31560 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
31570 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64  needs of the mod
31580 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
31590 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f  on..** The purpo
315a0 73 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72  se of this super
315b0 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69  class is to defi
315c0 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64  ne certain field
315d0 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f  s that are.** co
315e0 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75  mmon to all modu
315f0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
31600 6e 73 2e 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61  ns..**.** Virtua
31610 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73  l tables methods
31620 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f   can set an erro
31630 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73  r message by ass
31640 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69  igning a.** stri
31650 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
31660 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
31670 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e  f()] to zErrMsg.
31680 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f    The method sho
31690 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65  uld.** take care
316a0 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20   that any prior 
316b0 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20  string is freed 
316c0 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  by a call to [sq
316d0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a  lite3_free()].**
316e0 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e   prior to assign
316f0 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67  ing a new string
31700 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 41 66   to zErrMsg.  Af
31710 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
31720 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
31730 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
31740 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
31750 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
31760 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
31770 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
31780 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
31790 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
317a0 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
317b0 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  roed..*/.struct 
317c0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20  sqlite3_vtab {. 
317d0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
317e0 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20  odule *pModule; 
317f0 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66   /* The module f
31800 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  or this virtual 
31810 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e  table */.  int n
31820 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20  Ref;            
31830 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f             /* NO
31840 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a   LONGER USED */.
31850 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b    char *zErrMsg;
31860 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31870 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61    /* Error messa
31880 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ge from sqlite3_
31890 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f  mprintf() */.  /
318a0 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
318b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
318c0 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
318d0 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
318e0 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
318f0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
31900 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72  ual Table Cursor
31910 20 4f 62 6a 65 63 74 20 20 7b 48 31 38 30 32 30   Object  {H18020
31920 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b 45  } <S20400>.** KE
31930 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
31940 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72  vtab_cursor {vir
31950 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f  tual table curso
31960 72 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  r}.** EXPERIMENT
31970 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b  AL.**.** Every [
31980 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
31990 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61  dule] implementa
319a0 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63  tion uses a subc
319b0 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  lass of the.** f
319c0 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75  ollowing structu
319d0 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20 63  re to describe c
319e0 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e  ursors that poin
319f0 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76  t into the.** [v
31a00 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e  irtual table] an
31a10 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f  d are used.** to
31a20 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68   loop through th
31a30 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e  e virtual table.
31a40 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63 72    Cursors are cr
31a50 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a  eated using the.
31a60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ** [sqlite3_modu
31a70 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e  le.xOpen | xOpen
31a80 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  ] method of the 
31a90 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64  module and are d
31aa0 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74  estroyed.** by t
31ab0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75  he [sqlite3_modu
31ac0 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f  le.xClose | xClo
31ad0 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 73  se] method.  Cus
31ae0 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a  sors are used.**
31af0 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72   by the [xFilter
31b00 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f  ], [xNext], [xEo
31b10 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61  f], [xColumn], a
31b20 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68  nd [xRowid] meth
31b30 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f  ods.** of the mo
31b40 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75  dule.  Each modu
31b50 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
31b60 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a  n will define.**
31b70 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
31b80 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74 75  a cursor structu
31b90 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f  re to suit its o
31ba0 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  wn needs..**.** 
31bb0 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20  This superclass 
31bc0 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20  exists in order 
31bd0 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73  to define fields
31be0 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20 74   of the cursor t
31bf0 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f  hat.** are commo
31c00 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  n to all impleme
31c10 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72  ntations..*/.str
31c20 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
31c30 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69  _cursor {.  sqli
31c40 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b  te3_vtab *pVtab;
31c50 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c        /* Virtual
31c60 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63   table of this c
31c70 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69  ursor */.  /* Vi
31c80 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c  rtual table impl
31c90 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
31ca0 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61   typically add a
31cb0 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
31cc0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
31cd0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20  PI3REF: Declare 
31ce0 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20  The Schema Of A 
31cf0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b 48  Virtual Table {H
31d00 31 38 32 38 30 7d 20 3c 53 32 30 34 30 30 3e 0a  18280} <S20400>.
31d10 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
31d20 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 43 72 65 61  **.** The [xCrea
31d30 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63  te] and [xConnec
31d40 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a  t] methods of a.
31d50 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
31d60 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74  e module] call t
31d70 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  his interface.**
31d80 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20   to declare the 
31d90 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65  format (the name
31da0 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20  s and datatypes 
31db0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20  of the columns) 
31dc0 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61  of.** the virtua
31dd0 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d  l tables they im
31de0 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49  plement..*/.SQLI
31df0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
31e00 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c  int sqlite3_decl
31e10 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33  are_vtab(sqlite3
31e20 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
31e30 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  SQL);../*.** CAP
31e40 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20  I3REF: Overload 
31e50 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41  A Function For A
31e60 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 7b   Virtual Table {
31e70 48 31 38 33 30 30 7d 20 3c 53 32 30 34 30 30 3e  H18300} <S20400>
31e80 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
31e90 0a 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74  .**.** Virtual t
31ea0 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64  ables can provid
31eb0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  e alternative im
31ec0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
31ed0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73   functions.** us
31ee0 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75  ing the [xFindFu
31ef0 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f  nction] method o
31f00 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
31f10 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a  able module].  .
31f20 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65  ** But global ve
31f30 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20  rsions of those 
31f40 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73  functions.** mus
31f50 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72  t exist in order
31f60 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65   to be overloade
31f70 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 41 50  d..**.** This AP
31f80 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61 20 67  I makes sure a g
31f90 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66  lobal version of
31fa0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
31fb0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
31fc0 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72   name and number
31fd0 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73 20 65   of parameters e
31fe0 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20 73 75  xists.  If no su
31ff0 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78 69 73  ch function exis
32000 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 69  ts.** before thi
32010 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65 64 2c  s API is called,
32020 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20   a new function 
32030 69 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65  is created.  The
32040 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
32050 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75  ** of the new fu
32060 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61  nction always ca
32070 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f  uses an exceptio
32080 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20  n to be thrown. 
32090 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66   So.** the new f
320a0 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67  unction is not g
320b0 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67  ood for anything
320c0 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73   by itself.  Its
320d0 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65   only.** purpose
320e0 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63   is to be a plac
320f0 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e  eholder function
32100 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
32110 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20  rloaded.** by a 
32120 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e  [virtual table].
32130 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52  .*/.SQLITE_EXPER
32140 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69  IMENTAL int sqli
32150 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f 66 75 6e  te3_overload_fun
32160 63 74 69 6f 6e 28 73 71 6c 69 74 65 33 2a 2c 20  ction(sqlite3*, 
32170 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
32180 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41 72 67 29  cName, int nArg)
32190 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  ;../*.** The int
321a0 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
321b0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
321c0 61 6e 69 73 6d 20 64 65 66 69 6e 65 64 20 61 62  anism defined ab
321d0 6f 76 65 20 28 62 61 63 6b 20 75 70 0a 2a 2a 20  ove (back up.** 
321e0 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20 72 65 6d  to a comment rem
321f0 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c 61 72 20  arkably similar 
32200 74 6f 20 74 68 69 73 20 6f 6e 65 29 20 69 73 20  to this one) is 
32210 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
32220 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
32230 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
32240 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
32250 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
32260 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
32270 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
32280 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
32290 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
322a0 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
322b0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
322c0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
322d0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
322e0 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  bilizes, we will
322f0 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
32300 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
32310 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
32320 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
32330 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
32340 74 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50  t..**.****** EXP
32350 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75 62 6a  ERIMENTAL - subj
32360 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69  ect to change wi
32370 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a 2a 2a  thout notice ***
32380 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a  ***********.*/..
32390 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
323a0 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f  A Handle To An O
323b0 70 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 30 30  pen BLOB {H17800
323c0 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 20 4b 45  } <S30230>.** KE
323d0 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61  YWORDS: {BLOB ha
323e0 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64  ndle} {BLOB hand
323f0 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  les}.**.** An in
32400 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
32410 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
32420 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e   an open BLOB on
32430 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
32440 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
32450 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
32460 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66  I/O] can be perf
32470 6f 72 6d 65 64 2e 0a 2a 2a 20 4f 62 6a 65 63 74  ormed..** Object
32480 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61  s of this type a
32490 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73  re created by [s
324a0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
324b0 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72  ()].** and destr
324c0 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
324d0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a  _blob_close()]..
324e0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
324f0 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64  blob_read()] and
32500 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
32510 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63  rite()] interfac
32520 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  es.** can be use
32530 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69  d to read or wri
32540 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74  te small subsect
32550 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ions of the BLOB
32560 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
32570 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
32580 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
32590 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
325a0 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e  e BLOB in bytes.
325b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
325c0 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ct sqlite3_blob 
325d0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f  sqlite3_blob;../
325e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
325f0 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49  pen A BLOB For I
32600 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b  ncremental I/O {
32610 48 31 37 38 31 30 7d 20 3c 53 33 30 32 33 30 3e  H17810} <S30230>
32620 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
32630 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b  rfaces opens a [
32640 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61  BLOB handle | ha
32650 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f  ndle] to the BLO
32660 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20  B located.** in 
32670 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e  row iRow, column
32680 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20   zColumn, table 
32690 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61  zTable in databa
326a0 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74  se zDb;.** in ot
326b0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73  her words, the s
326c0 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f  ame BLOB that wo
326d0 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20  uld be selected 
326e0 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  by:.**.** <pre>.
326f0 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43  **     SELECT zC
32700 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a  olumn FROM zDb.z
32710 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77  Table WHERE [row
32720 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c  id] = iRow;.** <
32730 2f 70 72 65 3e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  /pre> {END}.**.*
32740 2a 20 49 66 20 74 68 65 20 66 6c 61 67 73 20 70  * If the flags p
32750 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
32760 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42  zero, then the B
32770 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
32780 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72  r read.** and wr
32790 69 74 65 20 61 63 63 65 73 73 2e 20 49 66 20 69  ite access. If i
327a0 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42  t is zero, the B
327b0 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
327c0 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a  r read access..*
327d0 2a 20 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * It is not poss
327e0 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63  ible to open a c
327f0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61  olumn that is pa
32800 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f  rt of an index o
32810 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65  r primary .** ke
32820 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e  y for writing. ^
32830 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  If [foreign key 
32840 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65  constraints] are
32850 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20   enabled, it is 
32860 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
32870 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d   to open a colum
32880 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f  n that is part o
32890 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20  f a [child key] 
328a0 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a  for writing..**.
328b0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
328c0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
328d0 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61  s not the filena
328e0 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  me that contains
328f0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
32900 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20   but rather the 
32910 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66  symbolic name of
32920 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68   the database th
32930 61 74 0a 2a 2a 20 69 73 20 61 73 73 69 67 6e 65  at.** is assigne
32940 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  d when the datab
32950 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64  ase is connected
32960 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e   using [ATTACH].
32970 0a 2a 2a 20 46 6f 72 20 74 68 65 20 6d 61 69 6e  .** For the main
32980 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
32990 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
329a0 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20  e is "main"..** 
329b0 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c  For TEMP tables,
329c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
329d0 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a  me is "temp"..**
329e0 0a 2a 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20  .** On success, 
329f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
32a00 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20  eturned and the 
32a10 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  new [BLOB handle
32a20 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  ] is written.** 
32a30 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65  to *ppBlob. Othe
32a40 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
32a50 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
32a60 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73  d and *ppBlob is
32a70 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20   set.** to be a 
32a80 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  null pointer..**
32a90 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   This function s
32aa0 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  ets the [databas
32ab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72  e connection] er
32ac0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
32ad0 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62  sage.** accessib
32ae0 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  le via [sqlite3_
32af0 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b  errcode()] and [
32b00 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
32b10 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a  ] and related.**
32b20 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 4e 6f 74   functions.  Not
32b30 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c  e that the *ppBl
32b40 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  ob variable is a
32b50 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65  lways initialize
32b60 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68  d in a.** way th
32b70 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65  at makes it safe
32b80 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69   to invoke [sqli
32b90 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
32ba0 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20  ] on *ppBlob.** 
32bb0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
32bc0 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  e success or fai
32bd0 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75  lure of this rou
32be0 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  tine..**.** If t
32bf0 68 65 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c  he row that a BL
32c00 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73  OB handle points
32c10 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20   to is modified 
32c20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45  by an.** [UPDATE
32c30 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20  ], [DELETE], or 
32c40 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d  by [ON CONFLICT]
32c50 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a   side-effects.**
32c60 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68   then the BLOB h
32c70 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20  andle is marked 
32c80 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a  as "expired"..**
32c90 20 54 68 69 73 20 69 73 20 74 72 75 65 20 69 66   This is true if
32ca0 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   any column of t
32cb0 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65  he row is change
32cc0 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e  d, even a column
32cd0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74  .** other than t
32ce0 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20  he one the BLOB 
32cf0 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f  handle is open o
32d00 6e 2e 0a 2a 2a 20 43 61 6c 6c 73 20 74 6f 20 5b  n..** Calls to [
32d10 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
32d20 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
32d30 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
32d40 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64  for.** a expired
32d50 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69   BLOB handle fai
32d60 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e  l with an return
32d70 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
32d80 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 43 68 61 6e  _ABORT]..** Chan
32d90 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  ges written into
32da0 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f   a BLOB prior to
32db0 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69   the BLOB expiri
32dc0 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f  ng are not.** ro
32dd0 6c 6c 62 61 63 6b 20 62 79 20 74 68 65 20 65 78  llback by the ex
32de0 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  piration of the 
32df0 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e  BLOB.  Such chan
32e00 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61  ges will eventua
32e10 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66  lly.** commit if
32e20 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
32e30 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
32e40 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
32e50 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
32e60 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
32e70 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65 74 65  nterface to dete
32e80 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20 6f  rmine the size o
32e90 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 20  f.** the opened 
32ea0 62 6c 6f 62 2e 20 20 54 68 65 20 73 69 7a 65 20  blob.  The size 
32eb0 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e 6f  of a blob may no
32ec0 74 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  t be changed by 
32ed0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
32ee0 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50 44  e.  Use the [UPD
32ef0 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e 64  ATE] SQL command
32f00 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 73   to change the s
32f10 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f 62  ize of a.** blob
32f20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ..**.** The [sql
32f30 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
32f40 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ob()] and [sqlit
32f50 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
32f60 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  ob()] interfaces
32f70 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75 69 6c  .** and the buil
32f80 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20  t-in [zeroblob] 
32f90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  SQL function can
32fa0 20 62 65 20 75 73 65 64 2c 20 69 66 20 64 65 73   be used, if des
32fb0 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72 65 61  ired,.** to crea
32fc0 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a 65 72  te an empty, zer
32fd0 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20 69 6e  o-filled blob in
32fe0 20 77 68 69 63 68 20 74 6f 20 72 65 61 64 20 6f   which to read o
32ff0 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a 2a 2a  r write using.**
33000 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
33010 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  .**.** To avoid 
33020 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 2c  a resource leak,
33030 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42 4c 4f   every open [BLO
33040 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75 6c 64  B handle] should
33050 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62   eventually.** b
33060 65 20 72 65 6c 65 61 73 65 64 20 62 79 20 61 20  e released by a 
33070 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
33080 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a  _blob_close()]..
33090 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
330a0 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 31 33 5d 20  ts:.** [H17813] 
330b0 5b 48 31 37 38 31 34 5d 20 5b 48 31 37 38 31 36  [H17814] [H17816
330c0 5d 20 5b 48 31 37 38 31 39 5d 20 5b 48 31 37 38  ] [H17819] [H178
330d0 32 31 5d 20 5b 48 31 37 38 32 34 5d 0a 2a 2f 0a  21] [H17824].*/.
330e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
330f0 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33  _open(.  sqlite3
33100 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  *,.  const char 
33110 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68  *zDb,.  const ch
33120 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f  ar *zTable,.  co
33130 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
33140 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74  n,.  sqlite3_int
33150 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66  64 iRow,.  int f
33160 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f  lags,.  sqlite3_
33170 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b  blob **ppBlob.);
33180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33190 3a 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48  : Close A BLOB H
331a0 61 6e 64 6c 65 20 7b 48 31 37 38 33 30 7d 20 3c  andle {H17830} <
331b0 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 43 6c  S30230>.**.** Cl
331c0 6f 73 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  oses an open [BL
331d0 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a  OB handle]..**.*
331e0 2a 20 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42  * Closing a BLOB
331f0 20 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65   shall cause the
33200 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
33210 74 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a  tion to commit.*
33220 2a 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e  * if there are n
33230 6f 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e  o other BLOBs, n
33240 6f 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72  o pending prepar
33250 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61  ed statements, a
33260 6e 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  nd the.** databa
33270 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
33280 20 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20   in [autocommit 
33290 6d 6f 64 65 5d 2e 0a 2a 2a 20 49 66 20 61 6e 79  mode]..** If any
332a0 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64   writes were mad
332b0 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74  e to the BLOB, t
332c0 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c  hey might be hel
332d0 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e  d in cache.** un
332e0 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70  til the close op
332f0 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20  eration if they 
33300 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20  will fit..**.** 
33310 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42  Closing the BLOB
33320 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68   often forces th
33330 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74  e changes.** out
33340 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20   to disk and so 
33350 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72  if any I/O error
33360 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69  s occur, they wi
33370 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a  ll likely occur.
33380 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ** at the time w
33390 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20  hen the BLOB is 
333a0 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72  closed.  Any err
333b0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 64  ors that occur d
333c0 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67  uring.** closing
333d0 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 73   are reported as
333e0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
333f0 72 6e 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  rn value..**.** 
33400 54 68 65 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73  The BLOB is clos
33410 65 64 20 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c  ed unconditional
33420 6c 79 2e 20 20 45 76 65 6e 20 69 66 20 74 68 69  ly.  Even if thi
33430 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
33440 73 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f  s.** an error co
33450 64 65 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20  de, the BLOB is 
33460 73 74 69 6c 6c 20 63 6c 6f 73 65 64 2e 0a 2a 2a  still closed..**
33470 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74 68 69 73  .** Calling this
33480 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
33490 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 77 68  null pointer (wh
334a0 69 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20  ich as would be 
334b0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 66  returned.** by f
334c0 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73  ailed call to [s
334d0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
334e0 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c 65  ()]) is a harmle
334f0 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
33500 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
33510 20 5b 48 31 37 38 33 33 5d 20 5b 48 31 37 38 33   [H17833] [H1783
33520 36 5d 20 5b 48 31 37 38 33 39 5d 0a 2a 2f 0a 69  6] [H17839].*/.i
33530 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
33540 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c  close(sqlite3_bl
33550 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
33560 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54  PI3REF: Return T
33570 68 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70  he Size Of An Op
33580 65 6e 20 42 4c 4f 42 20 7b 48 31 37 38 34 30 7d  en BLOB {H17840}
33590 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20   <S30230>.**.** 
335a0 52 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  Returns the size
335b0 20 69 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65   in bytes of the
335c0 20 42 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65   BLOB accessible
335d0 20 76 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 63   via the .** suc
335e0 63 65 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64  cessfully opened
335f0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
33600 6e 20 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d  n its only argum
33610 65 6e 74 2e 20 20 54 68 65 0a 2a 2a 20 69 6e 63  ent.  The.** inc
33620 72 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f  remental blob I/
33630 4f 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f  O routines can o
33640 6e 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72  nly read or over
33650 77 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67  writing existing
33660 0a 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74  .** blob content
33670 3b 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68  ; they cannot ch
33680 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66  ange the size of
33690 20 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54   a blob..**.** T
336a0 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79  his routine only
336b0 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f   works on a [BLO
336c0 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20  B handle] which 
336d0 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64  has been created
336e0 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73  .** by a prior s
336f0 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
33700 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
33710 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63  open()] and whic
33720 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65  h has not.** bee
33730 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c  n closed by [sql
33740 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
33750 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79  )].  Passing any
33760 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69   other pointer i
33770 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75  n.** to this rou
33780 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20  tine results in 
33790 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
337a0 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62  obably undesirab
337b0 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  le behavior..**.
337c0 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
337d0 0a 2a 2a 20 5b 48 31 37 38 34 33 5d 0a 2a 2f 0a  .** [H17843].*/.
337e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
337f0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62  _bytes(sqlite3_b
33800 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  lob *);../*.** C
33810 41 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61  API3REF: Read Da
33820 74 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49  ta From A BLOB I
33830 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31  ncrementally {H1
33840 37 38 35 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a  7850} <S30230>.*
33850 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
33860 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  on is used to re
33870 61 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20  ad data from an 
33880 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
33890 65 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c  e] into a.** cal
338a0 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
338b0 66 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20  fer. N bytes of 
338c0 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20  data are copied 
338d0 69 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a  into buffer Z.**
338e0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42   from the open B
338f0 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74  LOB, starting at
33900 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e   offset iOffset.
33910 0a 2a 2a 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74  .**.** If offset
33920 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73   iOffset is less
33930 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72   than N bytes fr
33940 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  om the end of th
33950 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49  e BLOB,.** [SQLI
33960 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74  TE_ERROR] is ret
33970 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74  urned and no dat
33980 61 20 69 73 20 72 65 61 64 2e 20 20 49 66 20 4e  a is read.  If N
33990 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73 0a 2a   or iOffset is.*
339a0 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  * less than zero
339b0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
339c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
339d0 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61 64   no data is read
339e0 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66  ..** The size of
339f0 20 74 68 65 20 62 6c 6f 62 20 28 61 6e 64 20 68   the blob (and h
33a00 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d  ence the maximum
33a10 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66   value of N+iOff
33a20 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64  set).** can be d
33a30 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
33a40 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
33a50 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
33a60 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  face..**.** An a
33a70 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66  ttempt to read f
33a80 72 6f 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b  rom an expired [
33a90 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69  BLOB handle] fai
33aa0 6c 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72  ls with an.** er
33ab0 72 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c  ror code of [SQL
33ac0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a  ITE_ABORT]..**.*
33ad0 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51  * On success, SQ
33ae0 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72  LITE_OK is retur
33af0 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  ned..** Otherwis
33b00 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  e, an [error cod
33b10 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
33b20 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
33b30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
33b40 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
33b50 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
33b60 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
33b70 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
33b80 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
33b90 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
33ba0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
33bb0 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
33bc0 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
33bd0 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
33be0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
33bf0 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
33c00 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
33c10 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
33c20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
33c30 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
33c40 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
33c50 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
33c60 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
33c70 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
33c80 69 74 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  ite()]..**.** Re
33c90 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
33ca0 48 31 37 38 35 33 5d 20 5b 48 31 37 38 35 36 5d  H17853] [H17856]
33cb0 20 5b 48 31 37 38 35 39 5d 20 5b 48 31 37 38 36   [H17859] [H1786
33cc0 32 5d 20 5b 48 31 37 38 36 33 5d 20 5b 48 31 37  2] [H17863] [H17
33cd0 38 36 35 5d 20 5b 48 31 37 38 36 38 5d 0a 2a 2f  865] [H17868].*/
33ce0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
33cf0 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33 5f 62  b_read(sqlite3_b
33d00 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20  lob *, void *Z, 
33d10 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66 66 73  int N, int iOffs
33d20 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
33d30 33 52 45 46 3a 20 57 72 69 74 65 20 44 61 74 61  3REF: Write Data
33d40 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49 6e 63   Into A BLOB Inc
33d50 72 65 6d 65 6e 74 61 6c 6c 79 20 7b 48 31 37 38  rementally {H178
33d60 37 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a 0a  70} <S30230>.**.
33d70 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
33d80 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69 74   is used to writ
33d90 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20 6f  e data into an o
33da0 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  pen [BLOB handle
33db0 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c 6c  ] from a.** call
33dc0 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66  er-supplied buff
33dd0 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64  er. N bytes of d
33de0 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 66  ata are copied f
33df0 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72 20 5a  rom the buffer Z
33e00 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f 70 65  .** into the ope
33e10 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69 6e 67  n BLOB, starting
33e20 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66 66 73   at offset iOffs
33e30 65 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  et..**.** If the
33e40 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70   [BLOB handle] p
33e50 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
33e60 73 74 20 61 72 67 75 6d 65 6e 74 20 77 61 73 20  st argument was 
33e70 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a  not opened for.*
33e80 2a 20 77 72 69 74 69 6e 67 20 28 74 68 65 20 66  * writing (the f
33e90 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
33ea0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
33eb0 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f  open()] was zero
33ec0 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  ),.** this funct
33ed0 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ion returns [SQL
33ee0 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a  ITE_READONLY]..*
33ef0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
33f00 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69  on may only modi
33f10 66 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20  fy the contents 
33f20 6f 66 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20  of the BLOB; it 
33f30 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  is.** not possib
33f40 6c 65 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74  le to increase t
33f50 68 65 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f  he size of a BLO
33f60 42 20 75 73 69 6e 67 20 74 68 69 73 20 41 50 49  B using this API
33f70 2e 0a 2a 2a 20 49 66 20 6f 66 66 73 65 74 20 69  ..** If offset i
33f80 4f 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74  Offset is less t
33f90 68 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d  han N bytes from
33fa0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
33fb0 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  BLOB,.** [SQLITE
33fc0 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72  _ERROR] is retur
33fd0 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20  ned and no data 
33fe0 69 73 20 77 72 69 74 74 65 6e 2e 20 20 49 66 20  is written.  If 
33ff0 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
34000 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45  n zero [SQLITE_E
34010 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
34020 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
34030 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65   written..** The
34040 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
34050 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65  B (and hence the
34060 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f   maximum value o
34070 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20  f N+iOffset).** 
34080 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
34090 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
340a0 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
340b0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
340c0 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 74  .** An attempt t
340d0 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78  o write to an ex
340e0 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64  pired [BLOB hand
340f0 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61  le] fails with a
34100 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  n.** error code 
34110 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  of [SQLITE_ABORT
34120 5d 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  ].  Writes to th
34130 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75  e BLOB that occu
34140 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74  rred.** before t
34150 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  he [BLOB handle]
34160 20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74   expired are not
34170 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20   rolled back by 
34180 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f  the.** expiratio
34190 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c  n of the handle,
341a0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
341b0 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  e those changes 
341c0 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65  might.** have be
341d0 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  en overwritten b
341e0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
341f0 74 68 61 74 20 65 78 70 69 72 65 64 20 74 68 65  that expired the
34200 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20   BLOB handle.** 
34210 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65  or by other inde
34220 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e  pendent statemen
34230 74 73 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  ts..**.** On suc
34240 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20  cess, SQLITE_OK 
34250 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
34260 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 20 5b  Otherwise, an  [
34270 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61  error code] or a
34280 6e 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  n [extended erro
34290 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
342a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ned..**.** This 
342b0 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72  routine only wor
342c0 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61  ks on a [BLOB ha
342d0 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20  ndle] which has 
342e0 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20  been created.** 
342f0 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  by a prior succe
34300 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
34310 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
34320 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61  ()] and which ha
34330 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c  s not.** been cl
34340 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
34350 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20  _blob_close()]. 
34360 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68   Passing any oth
34370 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a  er pointer in.**
34380 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
34390 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
343a0 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
343b0 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ly undesirable b
343c0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53  ehavior..**.** S
343d0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
343e0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a  3_blob_read()]..
343f0 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
34400 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 37 33 5d 20  ts:.** [H17873] 
34410 5b 48 31 37 38 37 34 5d 20 5b 48 31 37 38 37 35  [H17874] [H17875
34420 5d 20 5b 48 31 37 38 37 36 5d 20 5b 48 31 37 38  ] [H17876] [H178
34430 37 37 5d 20 5b 48 31 37 38 37 39 5d 20 5b 48 31  77] [H17879] [H1
34440 37 38 38 32 5d 20 5b 48 31 37 38 38 35 5d 0a 2a  7882] [H17885].*
34450 2a 20 5b 48 31 37 38 38 38 5d 0a 2a 2f 0a 69 6e  * [H17888].*/.in
34460 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77  t sqlite3_blob_w
34470 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  rite(sqlite3_blo
34480 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 20  b *, const void 
34490 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 69  *z, int n, int i
344a0 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  Offset);../*.** 
344b0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
344c0 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20 4f 62  l File System Ob
344d0 6a 65 63 74 73 20 7b 48 31 31 32 30 30 7d 20 3c  jects {H11200} <
344e0 53 32 30 31 30 30 3e 0a 2a 2a 0a 2a 2a 20 41 20  S20100>.**.** A 
344f0 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74  virtual filesyst
34500 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b  em (VFS) is an [
34510 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
34520 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  ect.** that SQLi
34530 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72  te uses to inter
34540 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  act.** with the 
34550 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
34560 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f  ting system.  Mo
34570 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64 73  st SQLite builds
34580 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20   come with a.** 
34590 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56  single default V
345a0 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72 6f  FS that is appro
345b0 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 68  priate for the h
345c0 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a  ost computer..**
345d0 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 62   New VFSes can b
345e0 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64  e registered and
345f0 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 20   existing VFSes 
34600 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65  can be unregiste
34610 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  red..** The foll
34620 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  owing interfaces
34630 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a   are provided..*
34640 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
34650 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74 65  _vfs_find() inte
34660 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
34670 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46 53  pointer to a VFS
34680 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
34690 0a 2a 2a 20 4e 61 6d 65 73 20 61 72 65 20 63 61  .** Names are ca
346a0 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a 2a 2a  se sensitive..**
346b0 20 4e 61 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d   Names are zero-
346c0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
346d0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 49 66 20   strings..** If 
346e0 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63  there is no matc
346f0 68 2c 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  h, a NULL pointe
34700 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
34710 2a 20 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73  * If zVfsName is
34720 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64   NULL then the d
34730 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65  efault VFS is re
34740 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 4e 65  turned..**.** Ne
34750 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69  w VFSes are regi
34760 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69  stered with sqli
34770 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
34780 28 29 2e 0a 2a 2a 20 45 61 63 68 20 6e 65 77 20  ()..** Each new 
34790 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20  VFS becomes the 
347a0 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 74  default VFS if t
347b0 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67  he makeDflt flag
347c0 20 69 73 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20   is set..** The 
347d0 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20  same VFS can be 
347e0 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69  registered multi
347f0 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75  ple times withou
34800 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 54 6f 20  t injury..** To 
34810 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e 67  make an existing
34820 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64 65   VFS into the de
34830 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69 73  fault VFS, regis
34840 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a 20  ter it again.** 
34850 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66 6c  with the makeDfl
34860 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66 20  t flag set.  If 
34870 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56 46  two different VF
34880 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  Ses with the.** 
34890 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72 65  same name are re
348a0 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62 65  gistered, the be
348b0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
348c0 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56 46  ned.  If a.** VF
348d0 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  S is registered 
348e0 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61 74  with a name that
348f0 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20 65   is NULL or an e
34900 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a 20  mpty string,.** 
34910 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
34920 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
34930 2a 2a 0a 2a 2a 20 55 6e 72 65 67 69 73 74 65 72  **.** Unregister
34940 20 61 20 56 46 53 20 77 69 74 68 20 74 68 65 20   a VFS with the 
34950 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65  sqlite3_vfs_unre
34960 67 69 73 74 65 72 28 29 20 69 6e 74 65 72 66 61  gister() interfa
34970 63 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 64 65  ce..** If the de
34980 66 61 75 6c 74 20 56 46 53 20 69 73 20 75 6e 72  fault VFS is unr
34990 65 67 69 73 74 65 72 65 64 2c 20 61 6e 6f 74 68  egistered, anoth
349a0 65 72 20 56 46 53 20 69 73 20 63 68 6f 73 65 6e  er VFS is chosen
349b0 20 61 73 0a 2a 2a 20 74 68 65 20 64 65 66 61 75   as.** the defau
349c0 6c 74 2e 20 20 54 68 65 20 63 68 6f 69 63 65 20  lt.  The choice 
349d0 66 6f 72 20 74 68 65 20 6e 65 77 20 56 46 53 20  for the new VFS 
349e0 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
349f0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
34a00 3a 0a 2a 2a 20 5b 48 31 31 32 30 33 5d 20 5b 48  :.** [H11203] [H
34a10 31 31 32 30 36 5d 20 5b 48 31 31 32 30 39 5d 20  11206] [H11209] 
34a20 5b 48 31 31 32 31 32 5d 20 5b 48 31 31 32 31 35  [H11212] [H11215
34a30 5d 20 5b 48 31 31 32 31 38 5d 0a 2a 2f 0a 73 71  ] [H11218].*/.sq
34a40 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69 74  lite3_vfs *sqlit
34a50 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e 73  e3_vfs_find(cons
34a60 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d 65  t char *zVfsName
34a70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
34a80 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c 69  fs_register(sqli
34a90 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 61  te3_vfs*, int ma
34aa0 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71 6c  keDflt);.int sql
34ab0 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
34ac0 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ter(sqlite3_vfs*
34ad0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34ae0 45 46 3a 20 4d 75 74 65 78 65 73 20 7b 48 31 37  EF: Mutexes {H17
34af0 30 30 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  000} <S20000>.**
34b00 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
34b10 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72  ore uses these r
34b20 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65  outines for thre
34b30 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a  ad.** synchroniz
34b40 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68  ation. Though th
34b50 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ey are intended 
34b60 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20  for internal.** 
34b70 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63  use by SQLite, c
34b80 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  ode that links a
34b90 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73  gainst SQLite is
34ba0 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f  .** permitted to
34bb0 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73   use any of thes
34bc0 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
34bd0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75  * The SQLite sou
34be0 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e  rce code contain
34bf0 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  s multiple imple
34c00 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66  mentations.** of
34c10 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75   these mutex rou
34c20 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f  tines.  An appro
34c30 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74  priate implement
34c40 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65  ation.** is sele
34c50 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  cted automatical
34c60 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ly at compile-ti
34c70 6d 65 2e 20 20 54 68 65 20 66 6f 6c 6c 6f 77 69  me.  The followi
34c80 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ng.** implementa
34c90 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c 61  tions are availa
34ca0 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ble in the SQLit
34cb0 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  e core:.**.** <u
34cc0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  l>.** <li>   SQL
34cd0 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a 2a  ITE_MUTEX_OS2.**
34ce0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
34cf0 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a 20  UTEX_PTHREAD.** 
34d00 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
34d10 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e 20  TEX_W32.** <li> 
34d20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e    SQLITE_MUTEX_N
34d30 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  OOP.** </ul>.**.
34d40 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55  ** The SQLITE_MU
34d50 54 45 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65  TEX_NOOP impleme
34d60 6e 74 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74  ntation is a set
34d70 20 6f 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20   of routines.** 
34d80 74 68 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61  that does no rea
34d90 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73  l locking and is
34da0 20 61 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72   appropriate for
34db0 20 75 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e   use in.** a sin
34dc0 67 6c 65 2d 74 68 72 65 61 64 65 64 20 61 70 70  gle-threaded app
34dd0 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 53  lication.  The S
34de0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c  QLITE_MUTEX_OS2,
34df0 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
34e00 5f 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51  _PTHREAD, and SQ
34e10 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69  LITE_MUTEX_W32 i
34e20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a  mplementations.*
34e30 2a 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74  * are appropriat
34e40 65 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f  e for use on OS/
34e50 32 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e  2, Unix, and Win
34e60 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 53  dows..**.** If S
34e70 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
34e80 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
34e90 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70  E_MUTEX_APPDEF p
34ea0 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d  reprocessor.** m
34eb0 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69  acro defined (wi
34ec0 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54  th "-DSQLITE_MUT
34ed0 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74  EX_APPDEF=1"), t
34ee0 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20  hen no mutex.** 
34ef0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
34f00 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20  s included with 
34f10 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20  the library. In 
34f20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a  this case the.**
34f30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
34f40 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f  t supply a custo
34f50 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e  m mutex implemen
34f60 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65  tation using the
34f70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
34f80 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  IG_MUTEX] option
34f90 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
34fa0 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f  config() functio
34fb0 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c  n.** before call
34fc0 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ing sqlite3_init
34fd0 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20  ialize() or any 
34fe0 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c  other public sql
34ff0 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f  ite3_.** functio
35000 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c  n that calls sql
35010 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
35020 29 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 31 31  )..**.** {H17011
35030 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  } The sqlite3_mu
35040 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75 74  tex_alloc() rout
35050 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61 20  ine allocates a 
35060 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e 64  new.** mutex and
35070 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
35080 65 72 20 74 6f 20 69 74 2e 20 7b 48 31 37 30 31  er to it. {H1701
35090 32 7d 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  2} If it returns
350a0 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d 65   NULL.** that me
350b0 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65 78  ans that a mutex
350c0 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61 6c   could not be al
350d0 6c 6f 63 61 74 65 64 2e 20 7b 48 31 37 30 31 33  located. {H17013
350e0 7d 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  } SQLite.** will
350f0 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74 61 63   unwind its stac
35100 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20  k and return an 
35110 65 72 72 6f 72 2e 20 7b 48 31 37 30 31 34 7d 20  error. {H17014} 
35120 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
35130 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
35140 5f 61 6c 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20  _alloc() is one 
35150 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
35160 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a   constants:.**.*
35170 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
35180 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
35190 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  T.** <li>  SQLIT
351a0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
351b0 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
351c0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
351d0 41 53 54 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53  ASTER.** <li>  S
351e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
351f0 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20  IC_MEM.** <li>  
35200 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
35210 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e  TIC_MEM2.** <li>
35220 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
35230 54 41 54 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c  TATIC_PRNG.** <l
35240 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
35250 5f 53 54 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c  _STATIC_LRU.** <
35260 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
35270 58 5f 53 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a  X_STATIC_LRU2.**
35280 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 7b 48 31   </ul>.**.** {H1
35290 37 30 31 35 7d 20 54 68 65 20 66 69 72 73 74 20  7015} The first 
352a0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  two constants ca
352b0 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  use sqlite3_mute
352c0 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65  x_alloc() to cre
352d0 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74  ate.** a new mut
352e0 65 78 2e 20 20 54 68 65 20 6e 65 77 20 6d 75 74  ex.  The new mut
352f0 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65 20  ex is recursive 
35300 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  when SQLITE_MUTE
35310 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 69  X_RECURSIVE.** i
35320 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20 6e  s used but not n
35330 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77 68  ecessarily so wh
35340 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
35350 46 41 53 54 20 69 73 20 75 73 65 64 2e 20 7b 45  FAST is used. {E
35360 4e 44 7d 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  ND}.** The mutex
35370 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35380 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
35390 20 6d 61 6b 65 20 61 20 64 69 73 74 69 6e 63 74   make a distinct
353a0 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
353b0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
353c0 52 53 49 56 45 20 61 6e 64 20 53 51 4c 49 54 45  RSIVE and SQLITE
353d0 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 66 20 69  _MUTEX_FAST if i
353e0 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  t does.** not wa
353f0 6e 74 20 74 6f 2e 20 20 7b 48 31 37 30 31 36 7d  nt to.  {H17016}
35400 20 42 75 74 20 53 51 4c 69 74 65 20 77 69 6c 6c   But SQLite will
35410 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20   only request a 
35420 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 20  recursive mutex 
35430 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72  in.** cases wher
35440 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64  e it really need
35450 73 20 6f 6e 65 2e 20 20 7b 45 4e 44 7d 20 49 66  s one.  {END} If
35460 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d 72 65   a faster non-re
35470 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a 2a 2a  cursive mutex.**
35480 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35490 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20  is available on 
354a0 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66 6f 72  the host platfor
354b0 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73 75 62  m, the mutex sub
354c0 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68 74 20  system.** might 
354d0 72 65 74 75 72 6e 20 73 75 63 68 20 61 20 6d 75  return such a mu
354e0 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  tex in response 
354f0 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  to SQLITE_MUTEX_
35500 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37  FAST..**.** {H17
35510 30 31 37 7d 20 54 68 65 20 6f 74 68 65 72 20 61  017} The other a
35520 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74 65 72  llowed parameter
35530 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74  s to sqlite3_mut
35540 65 78 5f 61 6c 6c 6f 63 28 29 20 65 61 63 68 20  ex_alloc() each 
35550 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e  return.** a poin
35560 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63 20  ter to a static 
35570 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65  preexisting mute
35580 78 2e 20 7b 45 4e 44 7d 20 20 53 69 78 20 73 74  x. {END}  Six st
35590 61 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65  atic mutexes are
355a0 0a 2a 2a 20 75 73 65 64 20 62 79 20 74 68 65 20  .** used by the 
355b0 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 20  current version 
355c0 6f 66 20 53 51 4c 69 74 65 2e 20 20 46 75 74 75  of SQLite.  Futu
355d0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
355e0 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20 61 64 64  QLite.** may add
355f0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 61 74   additional stat
35600 69 63 20 6d 75 74 65 78 65 73 2e 20 20 53 74 61  ic mutexes.  Sta
35610 74 69 63 20 6d 75 74 65 78 65 73 20 61 72 65 20  tic mutexes are 
35620 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20  for internal.** 
35630 75 73 65 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  use by SQLite on
35640 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ly.  Application
35650 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74  s that use SQLit
35660 65 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64  e mutexes should
35670 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20 74 68 65  .** use only the
35680 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73   dynamic mutexes
35690 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
356a0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 6f  ITE_MUTEX_FAST o
356b0 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45  r.** SQLITE_MUTE
356c0 58 5f 52 45 43 55 52 53 49 56 45 2e 0a 2a 2a 0a  X_RECURSIVE..**.
356d0 2a 2a 20 7b 48 31 37 30 31 38 7d 20 4e 6f 74 65  ** {H17018} Note
356e0 20 74 68 61 74 20 69 66 20 6f 6e 65 20 6f 66 20   that if one of 
356f0 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  the dynamic mute
35700 78 20 70 61 72 61 6d 65 74 65 72 73 20 28 53 51  x parameters (SQ
35710 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a  LITE_MUTEX_FAST.
35720 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54  ** or SQLITE_MUT
35730 45 58 5f 52 45 43 55 52 53 49 56 45 29 20 69 73  EX_RECURSIVE) is
35740 20 75 73 65 64 20 74 68 65 6e 20 73 71 6c 69 74   used then sqlit
35750 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
35760 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 64 69  .** returns a di
35770 66 66 65 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e  fferent mutex on
35780 20 65 76 65 72 79 20 63 61 6c 6c 2e 20 20 7b 48   every call.  {H
35790 31 37 30 33 34 7d 20 42 75 74 20 66 6f 72 20 74  17034} But for t
357a0 68 65 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74  he static.** mut
357b0 65 78 20 74 79 70 65 73 2c 20 74 68 65 20 73 61  ex types, the sa
357c0 6d 65 20 6d 75 74 65 78 20 69 73 20 72 65 74 75  me mutex is retu
357d0 72 6e 65 64 20 6f 6e 20 65 76 65 72 79 20 63 61  rned on every ca
357e0 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 74  ll that has.** t
357f0 68 65 20 73 61 6d 65 20 74 79 70 65 20 6e 75 6d  he same type num
35800 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30  ber..**.** {H170
35810 31 39 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f  19} The sqlite3_
35820 6d 75 74 65 78 5f 66 72 65 65 28 29 20 72 6f 75  mutex_free() rou
35830 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61 74 65 73  tine deallocates
35840 20 61 20 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a   a previously.**
35850 20 61 6c 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d   allocated dynam
35860 69 63 20 6d 75 74 65 78 2e 20 7b 48 31 37 30 32  ic mutex. {H1702
35870 30 7d 20 53 51 4c 69 74 65 20 69 73 20 63 61 72  0} SQLite is car
35880 65 66 75 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61  eful to dealloca
35890 74 65 20 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61  te every.** dyna
358a0 6d 69 63 20 6d 75 74 65 78 20 74 68 61 74 20 69  mic mutex that i
358b0 74 20 61 6c 6c 6f 63 61 74 65 73 2e 20 7b 41 31  t allocates. {A1
358c0 37 30 32 31 7d 20 54 68 65 20 64 79 6e 61 6d 69  7021} The dynami
358d0 63 20 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e  c mutexes must n
358e0 6f 74 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20  ot be in.** use 
358f0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 64 65  when they are de
35900 61 6c 6c 6f 63 61 74 65 64 2e 20 7b 41 31 37 30  allocated. {A170
35910 32 32 7d 20 41 74 74 65 6d 70 74 69 6e 67 20 74  22} Attempting t
35920 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 20 73  o deallocate a s
35930 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72  tatic.** mutex r
35940 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
35950 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 20 7b 48  ned behavior. {H
35960 31 37 30 32 33 7d 20 53 51 4c 69 74 65 20 6e 65  17023} SQLite ne
35970 76 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a  ver deallocates.
35980 2a 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65  ** a static mute
35990 78 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 54  x. {END}.**.** T
359a0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
359b0 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c  _enter() and sql
359c0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
359d0 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
359e0 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20  t.** to enter a 
359f0 6d 75 74 65 78 2e 20 7b 48 31 37 30 32 34 7d 20  mutex. {H17024} 
35a00 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
35a10 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69 74  d is already wit
35a20 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a 2a  hin the mutex,.*
35a30 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
35a40 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c 6f  enter() will blo
35a50 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  ck and sqlite3_m
35a60 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c 20  utex_try() will 
35a70 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
35a80 5f 42 55 53 59 2e 20 7b 48 31 37 30 32 35 7d 20  _BUSY. {H17025} 
35a90 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74   The sqlite3_mut
35aa0 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66 61  ex_try() interfa
35ab0 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ce returns [SQLI
35ac0 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20 73  TE_OK].** upon s
35ad0 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79 2e  uccessful entry.
35ae0 20 20 7b 48 31 37 30 32 36 7d 20 4d 75 74 65 78    {H17026} Mutex
35af0 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
35b00 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  .** SQLITE_MUTEX
35b10 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e 20 62  _RECURSIVE can b
35b20 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74 69 70  e entered multip
35b30 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68 65 20  le times by the 
35b40 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a 2a 20  same thread..** 
35b50 7b 48 31 37 30 32 37 7d 20 49 6e 20 73 75 63 68  {H17027} In such
35b60 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20 6d   cases the,.** m
35b70 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78 69  utex must be exi
35b80 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75 6d  ted an equal num
35b90 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65 66  ber of times bef
35ba0 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72 65  ore another thre
35bb0 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72 2e  ad.** can enter.
35bc0 20 20 7b 41 31 37 30 32 38 7d 20 49 66 20 74 68    {A17028} If th
35bd0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 74 72  e same thread tr
35be0 69 65 73 20 74 6f 20 65 6e 74 65 72 20 61 6e 79  ies to enter any
35bf0 20 6f 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f   other.** kind o
35c00 66 20 6d 75 74 65 78 20 6d 6f 72 65 20 74 68 61  f mutex more tha
35c10 6e 20 6f 6e 63 65 2c 20 74 68 65 20 62 65 68 61  n once, the beha
35c20 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
35c30 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 39 7d 20 53  d..** {H17029} S
35c40 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
35c50 20 65 78 68 69 62 69 74 0a 2a 2a 20 73 75 63 68   exhibit.** such
35c60 20 62 65 68 61 76 69 6f 72 20 69 6e 20 69 74 73   behavior in its
35c70 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d 75 74 65   own use of mute
35c80 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20  xes..**.** Some 
35c90 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61  systems (for exa
35ca0 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35  mple, Windows 95
35cb0 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74  ) do not support
35cc0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
35cd0 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  * implemented by
35ce0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
35cf0 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20  ry().  On those 
35d00 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33  systems, sqlite3
35d10 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20  _mutex_try().** 
35d20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
35d30 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20  rn SQLITE_BUSY. 
35d40 20 7b 48 31 37 30 33 30 7d 20 54 68 65 20 53 51   {H17030} The SQ
35d50 4c 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65  Lite core only e
35d60 76 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69  ver uses.** sqli
35d70 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20  te3_mutex_try() 
35d80 61 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69  as an optimizati
35d90 6f 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61 63  on so this is ac
35da0 63 65 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f  ceptable behavio
35db0 72 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 33 31  r..**.** {H17031
35dc0 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75  } The sqlite3_mu
35dd0 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74  tex_leave() rout
35de0 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74 65  ine exits a mute
35df0 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72  x that was.** pr
35e00 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64  eviously entered
35e10 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72   by the same thr
35e20 65 61 64 2e 20 20 7b 41 31 37 30 33 32 7d 20 54  ead.  {A17032} T
35e30 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
35e40 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66 20 74  s undefined if t
35e50 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f 74 20  he mutex is not 
35e60 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
35e70 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  d by the.** call
35e80 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20 69 73  ing thread or is
35e90 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 61   not currently a
35ea0 6c 6c 6f 63 61 74 65 64 2e 20 20 7b 48 31 37 30  llocated.  {H170
35eb0 33 33 7d 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  33} SQLite will.
35ec0 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74 68  ** never do eith
35ed0 65 72 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20  er. {END}.**.** 
35ee0 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
35ef0 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
35f00 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65  _enter(), sqlite
35f10 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f  3_mutex_try(), o
35f20 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  r.** sqlite3_mut
35f30 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20  ex_leave() is a 
35f40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
35f50 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75  en all three rou
35f60 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20  tines.** behave 
35f70 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  as no-ops..**.**
35f80 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
35f90 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
35fa0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d  ] and [sqlite3_m
35fb0 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e  utex_notheld()].
35fc0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65  .*/.sqlite3_mute
35fd0 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  x *sqlite3_mutex
35fe0 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  _alloc(int);.voi
35ff0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
36000 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74  free(sqlite3_mut
36010 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ex*);.void sqlit
36020 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73  e3_mutex_enter(s
36030 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
36040 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  int sqlite3_mute
36050 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75  x_try(sqlite3_mu
36060 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
36070 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
36080 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
36090 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
360a0 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20  : Mutex Methods 
360b0 4f 62 6a 65 63 74 20 7b 48 31 37 31 32 30 7d 20  Object {H17120} 
360c0 3c 53 32 30 31 33 30 3e 0a 2a 2a 20 45 58 50 45  <S20130>.** EXPE
360d0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41  RIMENTAL.**.** A
360e0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
360f0 69 73 20 73 74 72 75 63 74 75 72 65 20 64 65 66  is structure def
36100 69 6e 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76  ines the low-lev
36110 65 6c 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75  el routines.** u
36120 73 65 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  sed to allocate 
36130 61 6e 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e  and use mutexes.
36140 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20  .**.** Usually, 
36150 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
36160 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  x implementation
36170 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 53 51  s provided by SQ
36180 4c 69 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66  Lite are.** suff
36190 69 63 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20  icient, however 
361a0 74 68 65 20 75 73 65 72 20 68 61 73 20 74 68 65  the user has the
361b0 20 6f 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74   option of subst
361c0 69 74 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d  ituting a custom
361d0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
361e0 6f 6e 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a  on for specializ
361f0 65 64 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f  ed deployments o
36200 72 20 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68  r systems for wh
36210 69 63 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f  ich SQLite.** do
36220 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  es not provide a
36230 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
36240 65 6e 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69  entation. In thi
36250 73 20 63 61 73 65 2c 20 74 68 65 20 75 73 65 72  s case, the user
36260 0a 2a 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20  .** creates and 
36270 70 6f 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73  populates an ins
36280 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
36290 72 75 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a  ructure to pass.
362a0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
362b0 6e 66 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74  nfig() along wit
362c0 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  h the [SQLITE_CO
362d0 4e 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69  NFIG_MUTEX] opti
362e0 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  on..** Additiona
362f0 6c 6c 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65  lly, an instance
36300 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
36310 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  re can be used a
36320 73 20 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76  s an.** output v
36330 61 72 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65  ariable when que
36340 72 79 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d  rying the system
36350 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
36360 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d   mutex.** implem
36370 65 6e 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20  entation, using 
36380 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
36390 49 47 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74  IG_GETMUTEX] opt
363a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ion..**.** The x
363b0 4d 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64  MutexInit method
363c0 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73   defined by this
363d0 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e   structure is in
363e0 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  voked as.** part
363f0 20 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69   of system initi
36400 61 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65  alization by the
36410 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
36420 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a  ize() function..
36430 2a 2a 20 7b 48 31 37 30 30 31 7d 20 54 68 65 20  ** {H17001} The 
36440 78 4d 75 74 65 78 49 6e 69 74 20 72 6f 75 74 69  xMutexInit routi
36450 6e 65 20 73 68 61 6c 6c 20 62 65 20 63 61 6c 6c  ne shall be call
36460 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 63  ed by SQLite onc
36470 65 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66  e for each.** ef
36480 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
36490 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
364a0 69 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  ize()]..**.** Th
364b0 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68  e xMutexEnd meth
364c0 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68  od defined by th
364d0 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  is structure is 
364e0 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61  invoked as.** pa
364f0 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75  rt of system shu
36500 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71 6c  tdown by the sql
36510 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
36520 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a  function. The.**
36530 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36540 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69  of this method i
36550 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 72 65  s expected to re
36560 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 61  lease all outsta
36570 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63  nding.** resourc
36580 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74  es obtained by t
36590 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73  he mutex methods
365a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c   implementation,
365b0 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74   especially.** t
365c0 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62 79  hose obtained by
365d0 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20   the xMutexInit 
365e0 6d 65 74 68 6f 64 2e 20 7b 48 31 37 30 30 33 7d  method. {H17003}
365f0 20 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29   The xMutexEnd()
36600 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68  .** interface sh
36610 61 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 20 6f  all be invoked o
36620 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63 61 6c  nce for each cal
36630 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 68  l to [sqlite3_sh
36640 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a  utdown()]..**.**
36650 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 73   The remaining s
36660 65 76 65 6e 20 6d 65 74 68 6f 64 73 20 64 65 66  even methods def
36670 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72  ined by this str
36680 75 63 74 75 72 65 20 28 78 4d 75 74 65 78 41 6c  ucture (xMutexAl
36690 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72  loc,.** xMutexFr
366a0 65 65 2c 20 78 4d 75 74 65 78 45 6e 74 65 72 2c  ee, xMutexEnter,
366b0 20 78 4d 75 74 65 78 54 72 79 2c 20 78 4d 75 74   xMutexTry, xMut
366c0 65 78 4c 65 61 76 65 2c 20 78 4d 75 74 65 78 48  exLeave, xMutexH
366d0 65 6c 64 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65  eld and.** xMute
366e0 78 4e 6f 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d  xNotheld) implem
366f0 65 6e 74 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ent the followin
36700 67 20 69 6e 74 65 72 66 61 63 65 73 20 28 72 65  g interfaces (re
36710 73 70 65 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a  spectively):.**.
36720 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
36730 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
36740 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e  x_alloc()] </li>
36750 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
36760 69 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28  ite3_mutex_free(
36770 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
36780 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
36790 65 78 5f 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69  ex_enter()] </li
367a0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
367b0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
367c0 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
367d0 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
367e0 65 78 5f 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69  ex_leave()] </li
367f0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
36800 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
36810 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
36820 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
36830 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c  tex_notheld()] <
36840 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
36850 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  .** The only dif
36860 66 65 72 65 6e 63 65 20 69 73 20 74 68 61 74 20  ference is that 
36870 74 68 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74  the public sqlit
36880 65 33 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73  e3_XXX functions
36890 20 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61   enumerated.** a
368a0 62 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67  bove silently ig
368b0 6e 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74  nore any invocat
368c0 69 6f 6e 73 20 74 68 61 74 20 70 61 73 73 20 61  ions that pass a
368d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e   NULL pointer in
368e0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61  stead.** of a va
368f0 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65  lid mutex handle
36900 2e 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  . The implementa
36910 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74  tions of the met
36920 68 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20  hods defined.** 
36930 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72  by this structur
36940 65 20 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72  e are not requir
36950 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69  ed to handle thi
36960 73 20 63 61 73 65 2c 20 74 68 65 20 72 65 73 75  s case, the resu
36970 6c 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e  lts.** of passin
36980 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
36990 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61   instead of a va
369a0 6c 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65  lid mutex handle
369b0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a   are undefined.*
369c0 2a 20 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63  * (i.e. it is ac
369d0 63 65 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76  ceptable to prov
369e0 69 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  ide an implement
369f0 61 74 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61  ation that segfa
36a00 75 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73  ults if.** it is
36a10 20 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70   passed a NULL p
36a20 6f 69 6e 74 65 72 29 2e 0a 2a 2a 0a 2a 2a 20 54  ointer)..**.** T
36a30 68 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20  he xMutexInit() 
36a40 6d 65 74 68 6f 64 20 6d 75 73 74 20 62 65 20 74  method must be t
36a50 68 72 65 61 64 73 61 66 65 2e 20 20 49 74 20 6d  hreadsafe.  It m
36a60 75 73 74 20 62 65 20 68 61 72 6d 6c 65 73 73 20  ust be harmless 
36a70 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 78 4d 75  to.** invoke xMu
36a80 74 65 78 49 6e 69 74 28 29 20 6d 75 74 69 70 6c  texInit() mutipl
36a90 65 20 74 69 6d 65 73 20 77 69 74 68 69 6e 20 74  e times within t
36aa0 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 20  he same process 
36ab0 61 6e 64 20 77 69 74 68 6f 75 74 0a 2a 2a 20 69  and without.** i
36ac0 6e 74 65 72 76 65 6e 69 6e 67 20 63 61 6c 6c 73  ntervening calls
36ad0 20 74 6f 20 78 4d 75 74 65 78 45 6e 64 28 29 2e   to xMutexEnd().
36ae0 20 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62    Second and sub
36af0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
36b00 0a 2a 2a 20 78 4d 75 74 65 78 49 6e 69 74 28 29  .** xMutexInit()
36b10 20 6d 75 73 74 20 62 65 20 6e 6f 2d 6f 70 73 2e   must be no-ops.
36b20 0a 2a 2a 0a 2a 2a 20 78 4d 75 74 65 78 49 6e 69  .**.** xMutexIni
36b30 74 28 29 20 6d 75 73 74 20 6e 6f 74 20 75 73 65  t() must not use
36b40 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61   SQLite memory a
36b50 6c 6c 6f 63 61 74 69 6f 6e 20 28 5b 73 71 6c 69  llocation ([sqli
36b60 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
36b70 20 61 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61   and its associa
36b80 74 65 73 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  tes).  Similarly
36b90 2c 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20  , xMutexAlloc() 
36ba0 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c  must not use SQL
36bb0 69 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ite memory.** al
36bc0 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 73  location for a s
36bd0 74 61 74 69 63 20 6d 75 74 65 78 2e 20 20 48 6f  tatic mutex.  Ho
36be0 77 65 76 65 72 20 78 4d 75 74 65 78 41 6c 6c 6f  wever xMutexAllo
36bf0 63 28 29 20 6d 61 79 20 75 73 65 20 53 51 4c 69  c() may use SQLi
36c00 74 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  te.** memory all
36c10 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20 66 61  ocation for a fa
36c20 73 74 20 6f 72 20 72 65 63 75 72 73 69 76 65 20  st or recursive 
36c30 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  mutex..**.** SQL
36c40 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
36c50 74 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29 20  the xMutexEnd() 
36c60 6d 65 74 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c  method when [sql
36c70 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
36c80 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62   is.** called, b
36c90 75 74 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  ut only if the p
36ca0 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75  rior call to xMu
36cb0 74 65 78 49 6e 69 74 20 72 65 74 75 72 6e 65 64  texInit returned
36cc0 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49   SQLITE_OK..** I
36cd0 66 20 78 4d 75 74 65 78 49 6e 69 74 20 66 61 69  f xMutexInit fai
36ce0 6c 73 20 69 6e 20 61 6e 79 20 77 61 79 2c 20 69  ls in any way, i
36cf0 74 20 69 73 20 65 78 70 65 63 74 65 64 20 74 6f  t is expected to
36d00 20 63 6c 65 61 6e 20 75 70 20 61 66 74 65 72 20   clean up after 
36d10 69 74 73 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20  itself.** prior 
36d20 74 6f 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f  to returning..*/
36d30 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
36d40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
36d50 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 75  thods sqlite3_mu
36d60 74 65 78 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  tex_methods;.str
36d70 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
36d80 78 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  x_methods {.  in
36d90 74 20 28 2a 78 4d 75 74 65 78 49 6e 69 74 29 28  t (*xMutexInit)(
36da0 76 6f 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  void);.  int (*x
36db0 4d 75 74 65 78 45 6e 64 29 28 76 6f 69 64 29 3b  MutexEnd)(void);
36dc0 0a 20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  .  sqlite3_mutex
36dd0 20 2a 28 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29   *(*xMutexAlloc)
36de0 28 69 6e 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a  (int);.  void (*
36df0 78 4d 75 74 65 78 46 72 65 65 29 28 73 71 6c 69  xMutexFree)(sqli
36e00 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
36e10 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 45 6e 74  void (*xMutexEnt
36e20 65 72 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  er)(sqlite3_mute
36e30 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
36e40 75 74 65 78 54 72 79 29 28 73 71 6c 69 74 65 33  utexTry)(sqlite3
36e50 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69  _mutex *);.  voi
36e60 64 20 28 2a 78 4d 75 74 65 78 4c 65 61 76 65 29  d (*xMutexLeave)
36e70 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
36e80 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
36e90 78 48 65 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d  xHeld)(sqlite3_m
36ea0 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28  utex *);.  int (
36eb0 2a 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 28  *xMutexNotheld)(
36ec0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
36ed0 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ;.};../*.** CAPI
36ee0 33 52 45 46 3a 20 4d 75 74 65 78 20 56 65 72 69  3REF: Mutex Veri
36ef0 66 69 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  fication Routine
36f00 73 20 7b 48 31 37 30 38 30 7d 20 3c 53 32 30 31  s {H17080} <S201
36f10 33 30 3e 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a  30> <S30800>.**.
36f20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
36f30 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20  utex_held() and 
36f40 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
36f50 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73  theld() routines
36f60 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64  .** are intended
36f70 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
36f80 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
36f90 6e 74 73 2e 20 7b 48 31 37 30 38 31 7d 20 54 68  nts. {H17081} Th
36fa0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a 2a 2a  e SQLite core.**
36fb0 20 6e 65 76 65 72 20 75 73 65 73 20 74 68 65 73   never uses thes
36fc0 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63 65 70  e routines excep
36fd0 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73 73 65  t inside an asse
36fe0 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69 63 61  rt() and applica
36ff0 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 64 76  tions.** are adv
37000 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 20 74  ised to follow t
37010 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65 20 63  he lead of the c
37020 6f 72 65 2e 20 20 7b 48 31 37 30 38 32 7d 20 54  ore.  {H17082} T
37030 68 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a 20  he core only.** 
37040 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d 65  provides impleme
37050 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  ntations for the
37060 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68 65 6e  se routines when
37070 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a   it is compiled.
37080 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ** with the SQLI
37090 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e 20 20  TE_DEBUG flag.  
370a0 7b 41 31 37 30 38 37 7d 20 45 78 74 65 72 6e 61  {A17087} Externa
370b0 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e  l mutex implemen
370c0 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f  tations.** are o
370d0 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f 20  nly required to 
370e0 70 72 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f  provide these ro
370f0 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45  utines if SQLITE
37100 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66  _DEBUG is.** def
37110 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42  ined and if NDEB
37120 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65  UG is not define
37130 64 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 33  d..**.** {H17083
37140 7d 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  } These routines
37150 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
37160 72 75 65 20 69 66 20 74 68 65 20 6d 75 74 65 78  rue if the mutex
37170 20 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d 65   in their argume
37180 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f 72  nt.** is held or
37190 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70 65   not held, respe
371a0 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65 20  ctively, by the 
371b0 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e 0a  calling thread..
371c0 2a 2a 0a 2a 2a 20 7b 58 31 37 30 38 34 7d 20 54  **.** {X17084} T
371d0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
371e0 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65  n is not require
371f0 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65  d to provided ve
37200 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a  rsions of these.
37210 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
37220 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20   actually work. 
37230 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  If the implement
37240 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70  ation does not p
37250 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a  rovide working.*
37260 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68  * versions of th
37270 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74  ese routines, it
37280 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74   should at least
37290 20 70 72 6f 76 69 64 65 20 73 74 75 62 73 20 74   provide stubs t
372a0 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65  hat always.** re
372b0 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61  turn true so tha
372c0 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67  t one does not g
372d0 65 74 20 73 70 75 72 69 6f 75 73 20 61 73 73 65  et spurious asse
372e0 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a  rtion failures..
372f0 2a 2a 0a 2a 2a 20 7b 48 31 37 30 38 35 7d 20 49  **.** {H17085} I
37300 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  f the argument t
37310 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
37320 68 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c 4c  held() is a NULL
37330 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
37340 20 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68 6f   the routine sho
37350 75 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20 7b  uld return 1.  {
37360 45 4e 44 7d 20 54 68 69 73 20 73 65 65 6d 73 20  END} This seems 
37370 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74 69 76  counter-intuitiv
37380 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c 65 61 72  e since.** clear
37390 6c 79 20 74 68 65 20 6d 75 74 65 78 20 63 61 6e  ly the mutex can
373a0 6e 6f 74 20 62 65 20 68 65 6c 64 20 69 66 20 69  not be held if i
373b0 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74  t does not exist
373c0 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a 20 74 68  .  But the.** th
373d0 65 20 72 65 61 73 6f 6e 20 74 68 65 20 6d 75 74  e reason the mut
373e0 65 78 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73  ex does not exis
373f0 74 20 69 73 20 62 65 63 61 75 73 65 20 74 68 65  t is because the
37400 20 62 75 69 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a   build is not.**
37410 20 75 73 69 6e 67 20 6d 75 74 65 78 65 73 2e 20   using mutexes. 
37420 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f 74 20 77   And we do not w
37430 61 6e 74 20 74 68 65 20 61 73 73 65 72 74 28 29  ant the assert()
37440 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
37450 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
37460 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20  e3_mutex_held() 
37470 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61 20 6e 6f  to fail, so a no
37480 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e 20 69 73  n-zero return is
37490 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f 70 72 69  .** the appropri
374a0 61 74 65 20 74 68 69 6e 67 20 74 6f 20 64 6f 2e  ate thing to do.
374b0 20 20 7b 48 31 37 30 38 36 7d 20 54 68 65 20 73    {H17086} The s
374c0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
374d0 68 65 6c 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66  held().** interf
374e0 61 63 65 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20  ace should also 
374f0 72 65 74 75 72 6e 20 31 20 77 68 65 6e 20 67 69  return 1 when gi
37500 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ven a NULL point
37510 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
37520 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 73 71  e3_mutex_held(sq
37530 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69  lite3_mutex*);.i
37540 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nt sqlite3_mutex
37550 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69 74 65 33  _notheld(sqlite3
37560 5f 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _mutex*);../*.**
37570 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
37580 20 54 79 70 65 73 20 7b 48 31 37 30 30 31 7d 20   Types {H17001} 
37590 3c 48 31 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H17000>.**.** T
375a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
375b0 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72  x_alloc()] inter
375c0 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e  face takes a sin
375d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  gle argument.** 
375e0 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20  which is one of 
375f0 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  these integer co
37600 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nstants..**.** T
37610 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 69 63  he set of static
37620 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68 61   mutexes may cha
37630 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c  nge from one SQL
37640 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  ite release to t
37650 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
37660 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f  lications that o
37670 76 65 72 72 69 64 65 20 74 68 65 20 62 75 69 6c  verride the buil
37680 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63  t-in mutex logic
37690 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65 70   must be.** prep
376a0 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64  ared to accommod
376b0 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  ate additional s
376c0 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a  tatic mutexes..*
376d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
376e0 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20 20  _MUTEX_FAST     
376f0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
37700 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  e SQLITE_MUTEX_R
37710 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
37720 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
37730 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
37740 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e  STER    2.#defin
37750 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
37760 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20  TATIC_MEM       
37770 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61  3  /* sqlite3_ma
37780 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e  lloc() */.#defin
37790 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
377a0 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20  TATIC_MEM2      
377b0 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a  4  /* NOT USED *
377c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
377d0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f 50  _MUTEX_STATIC_OP
377e0 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71  EN      4  /* sq
377f0 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28 29  lite3BtreeOpen()
37800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
37810 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
37820 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a 20  PRNG      5  /* 
37830 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29  sqlite3_random()
37840 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
37850 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
37860 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a 20  LRU       6  /* 
37870 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f  lru page list */
37880 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37890 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
378a0 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72 75  2      7  /* lru
378b0 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f   page list */../
378c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
378d0 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 74 65  etrieve the mute
378e0 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65  x for a database
378f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 37   connection {H17
37900 30 30 32 7d 20 3c 48 31 37 30 30 30 3e 0a 2a 2a  002} <H17000>.**
37910 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
37920 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
37930 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 65  nter the [sqlite
37940 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 20  3_mutex] object 
37950 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69  that .** seriali
37960 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74 68  zes access to th
37970 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37980 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e  ection] given in
37990 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
379a0 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65 61   when the [threa
379b0 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 65  ding mode] is Se
379c0 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 49 66 20  rialized..** If 
379d0 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
379e0 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 2d 74  ode] is Single-t
379f0 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 2d 74  hread or Multi-t
37a00 68 72 65 61 64 20 74 68 65 6e 20 74 68 69 73 0a  hread then this.
37a10 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
37a20 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
37a30 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75  r..*/.sqlite3_mu
37a40 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f  tex *sqlite3_db_
37a50 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a 29 3b  mutex(sqlite3*);
37a60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37a70 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e 74  : Low-Level Cont
37a80 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65 20  rol Of Database 
37a90 46 69 6c 65 73 20 7b 48 31 31 33 30 30 7d 20 3c  Files {H11300} <
37aa0 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 7b 48  S30800>.**.** {H
37ab0 31 31 33 30 31 7d 20 54 68 65 20 5b 73 71 6c 69  11301} The [sqli
37ac0 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
37ad0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d 61  ()] interface ma
37ae0 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61 6c  kes a direct cal
37af0 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c  l to the.** xFil
37b00 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
37b10 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
37b20 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
37b30 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  ect associated.*
37b40 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  * with a particu
37b50 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64 65  lar database ide
37b60 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
37b70 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20  econd argument. 
37b80 7b 48 31 31 33 30 32 7d 20 54 68 65 0a 2a 2a 20  {H11302} The.** 
37b90 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
37ba0 62 61 73 65 20 69 73 20 74 68 65 20 6e 61 6d 65  base is the name
37bb0 20 61 73 73 69 67 6e 65 64 20 74 6f 20 74 68 65   assigned to the
37bc0 20 64 61 74 61 62 61 73 65 20 62 79 20 74 68 65   database by the
37bd0 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 6c 61 6e  .** <a href="lan
37be0 67 5f 61 74 74 61 63 68 2e 68 74 6d 6c 22 3e 41  g_attach.html">A
37bf0 54 54 41 43 48 3c 2f 61 3e 20 53 51 4c 20 63 6f  TTACH</a> SQL co
37c00 6d 6d 61 6e 64 20 74 68 61 74 20 6f 70 65 6e 65  mmand that opene
37c10 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  d the.** databas
37c20 65 2e 20 7b 48 31 31 33 30 33 7d 20 54 6f 20 63  e. {H11303} To c
37c30 6f 6e 74 72 6f 6c 20 74 68 65 20 6d 61 69 6e 20  ontrol the main 
37c40 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 75  database file, u
37c50 73 65 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69  se the name "mai
37c60 6e 22 0a 2a 2a 20 6f 72 20 61 20 4e 55 4c 4c 20  n".** or a NULL 
37c70 70 6f 69 6e 74 65 72 2e 20 7b 48 31 31 33 30 34  pointer. {H11304
37c80 7d 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20  } The third and 
37c90 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
37ca0 73 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  s to this routin
37cb0 65 0a 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20  e.** are passed 
37cc0 64 69 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68  directly through
37cd0 20 74 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61   to the second a
37ce0 6e 64 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  nd third paramet
37cf0 65 72 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46  ers of.** the xF
37d00 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
37d10 64 2e 20 20 7b 48 31 31 33 30 35 7d 20 54 68 65  d.  {H11305} The
37d20 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
37d30 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
37d40 6c 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f  l.** method beco
37d50 6d 65 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  mes the return v
37d60 61 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75  alue of this rou
37d70 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 31  tine..**.** {H11
37d80 33 30 36 7d 20 49 66 20 74 68 65 20 73 65 63 6f  306} If the seco
37d90 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44  nd parameter (zD
37da0 62 4e 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20  bName) does not 
37db0 6d 61 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f  match the name o
37dc0 66 20 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61  f any.** open da
37dd0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65  tabase file, the
37de0 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69  n SQLITE_ERROR i
37df0 73 20 72 65 74 75 72 6e 65 64 2e 20 7b 48 31 31  s returned. {H11
37e00 33 30 37 7d 20 54 68 69 73 20 65 72 72 6f 72 0a  307} This error.
37e10 2a 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72  ** code is not r
37e20 65 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77 69  emembered and wi
37e30 6c 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c  ll not be recall
37e40 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65  ed by [sqlite3_e
37e50 72 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20  rrcode()].** or 
37e60 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
37e70 29 5d 2e 20 7b 41 31 31 33 30 38 7d 20 54 68 65  )]. {A11308} The
37e80 20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c   underlying xFil
37e90 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
37ea0 6d 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65  might.** also re
37eb0 74 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f  turn SQLITE_ERRO
37ec0 52 2e 20 20 7b 41 31 31 33 30 39 7d 20 54 68 65  R.  {A11309} The
37ed0 72 65 20 69 73 20 6e 6f 20 77 61 79 20 74 6f 20  re is no way to 
37ee0 64 69 73 74 69 6e 67 75 69 73 68 20 62 65 74 77  distinguish betw
37ef0 65 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72  een.** an incorr
37f00 65 63 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20  ect zDbName and 
37f10 61 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20  an SQLITE_ERROR 
37f20 72 65 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 20  return from the 
37f30 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46  underlying.** xF
37f40 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
37f50 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 53  d. {END}.**.** S
37f60 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
37f70 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
37f80 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
37f90 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71  _file_control(sq
37fa0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
37fb0 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74  ar *zDbName, int
37fc0 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   op, void*);../*
37fd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
37fe0 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 20  sting Interface 
37ff0 7b 48 31 31 34 30 30 7d 20 3c 53 33 30 38 30 30  {H11400} <S30800
38000 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
38010 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c  te3_test_control
38020 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
38030 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 74  used to read out
38040 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61   internal.** sta
38050 74 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e 64  te of SQLite and
38060 20 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c 74   to inject fault
38070 73 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f  s into SQLite fo
38080 72 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72  r testing.** pur
38090 70 6f 73 65 73 2e 20 20 54 68 65 20 66 69 72 73  poses.  The firs
380a0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
380b0 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65  n operation code
380c0 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
380d0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c 20  .** the number, 
380e0 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65  meaning, and ope
380f0 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75  ration of all su
38100 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
38110 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ers..**.** This 
38120 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
38130 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 70 6c   for use by appl
38140 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 78  ications.  It ex
38150 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66  ists solely.** f
38160 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 68 65  or verifying the
38170 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74 69   correct operati
38180 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
38190 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65 6e   library.  Depen
381a0 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74  ding.** on how t
381b0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
381c0 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74  y is compiled, t
381d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d 69  his interface mi
381e0 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a  ght not exist..*
381f0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
38200 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6f   of the operatio
38210 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20 6d  n codes, their m
38220 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 72  eanings, the par
38230 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 20  ameters.** they 
38240 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 74  take, and what t
38250 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 73  hey do are all s
38260 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
38270 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e   without notice.
38280 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20  .** Unlike most 
38290 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 50  of the SQLite AP
382a0 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  I, this function
382b0 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
382c0 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65  ed to.** operate
382d0 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 72   consistently fr
382e0 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
382f0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69  o the next..*/.i
38300 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  nt sqlite3_test_
38310 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20  control(int op, 
38320 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
38330 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49  I3REF: Testing I
38340 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 69  nterface Operati
38350 6f 6e 20 43 6f 64 65 73 20 7b 48 31 31 34 31 30  on Codes {H11410
38360 7d 20 3c 48 31 31 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <H11400>.**.**
38370 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
38380 20 61 72 65 20 74 68 65 20 76 61 6c 69 64 20 6f   are the valid o
38390 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 61  peration code pa
383a0 72 61 6d 65 74 65 72 73 20 75 73 65 64 0a 2a 2a  rameters used.**
383b0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
383c0 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
383d0 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28  e3_test_control(
383e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
383f0 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 74  parameters and t
38400 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 72  heir meanings ar
38410 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  e subject to cha
38420 6e 67 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e  nge.** without n
38430 6f 74 69 63 65 2e 20 20 54 68 65 73 65 20 76 61  otice.  These va
38440 6c 75 65 73 20 61 72 65 20 66 6f 72 20 74 65 73  lues are for tes
38450 74 69 6e 67 20 70 75 72 70 6f 73 65 73 20 6f 6e  ting purposes on
38460 6c 79 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  ly..** Applicati
38470 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75  ons should not u
38480 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  se any of these 
38490 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 74 68  parameters or th
384a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65  e.** [sqlite3_te
384b0 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  st_control()] in
384c0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
384d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
384e0 54 52 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 20  TRL_PRNG_SAVE   
384f0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23               5.#
38500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
38510 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54  STCTRL_PRNG_REST
38520 4f 52 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ORE             
38530 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
38540 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52  _TESTCTRL_PRNG_R
38550 45 53 45 54 20 20 20 20 20 20 20 20 20 20 20 20  ESET            
38560 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
38570 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 54  ITE_TESTCTRL_BIT
38580 56 45 43 5f 54 45 53 54 20 20 20 20 20 20 20 20  VEC_TEST        
38590 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
385a0 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f  SQLITE_TESTCTRL_
385b0 46 41 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20  FAULT_INSTALL   
385c0 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
385d0 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54  ne SQLITE_TESTCT
385e0 52 4c 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43  RL_BENIGN_MALLOC
385f0 5f 48 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23 64  _HOOKS     10.#d
38600 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53  efine SQLITE_TES
38610 54 43 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59  TCTRL_PENDING_BY
38620 54 45 20 20 20 20 20 20 20 20 20 20 20 20 31 31  TE            11
38630 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38640 54 45 53 54 43 54 52 4c 5f 41 53 53 45 52 54 20  TESTCTRL_ASSERT 
38650 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38660 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
38670 54 45 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57 41  TE_TESTCTRL_ALWA
38680 59 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20  YS              
38690 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53      13.#define S
386a0 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 52  QLITE_TESTCTRL_R
386b0 45 53 45 52 56 45 20 20 20 20 20 20 20 20 20 20  ESERVE          
386c0 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a         14../*.**
386d0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 69 74   CAPI3REF: SQLit
386e0 65 20 52 75 6e 74 69 6d 65 20 53 74 61 74 75 73  e Runtime Status
386f0 20 7b 48 31 37 32 30 30 7d 20 3c 53 36 30 32 30   {H17200} <S6020
38700 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
38710 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  AL.**.** This in
38720 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
38730 74 6f 20 72 65 74 72 69 65 76 65 20 72 75 6e 74  to retrieve runt
38740 69 6d 65 20 73 74 61 74 75 73 20 69 6e 66 6f 72  ime status infor
38750 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
38760 74 68 65 20 70 72 65 66 6f 72 6d 61 6e 63 65 20  the preformance 
38770 6f 66 20 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f  of SQLite, and o
38780 70 74 69 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73  ptionally to res
38790 65 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69  et various.** hi
387a0 67 68 77 61 74 65 72 20 6d 61 72 6b 73 2e 20 20  ghwater marks.  
387b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
387c0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
387d0 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65   code for.** the
387e0 20 73 70 65 63 69 66 69 63 20 70 61 72 61 6d 65   specific parame
387f0 74 65 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20  ter to measure. 
38800 20 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 65   Recognized inte
38810 67 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65  ger codes.** are
38820 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 51   of the form [SQ
38830 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f  LITE_STATUS_MEMO
388