/ Hex Artifact Content
Login

Artifact 94052f827890de6fb7c913b95507076909261d9b:


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 0a 2f 2a 0a  pen_v2() */../*.
4a00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
4a10: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
4a20: 69 63 73 20 7b 48 31 30 32 34 30 7d 20 3c 48 31  ics {H10240} <H1
4a30: 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  1120>.**.** The 
4a40: 78 44 65 76 69 63 65 43 61 70 61 62 69 6c 69 74  xDeviceCapabilit
4a50: 69 65 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ies method of th
4a60: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
4a70: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
4a80: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
4a90: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
4aa0: 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65  ector of the the
4ab0: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
4ac0: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
4ad0: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
4ae0: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
4af0: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
4b00: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
4b10: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
4b20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
4b30: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
4b40: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
4b50: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
4b60: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
4b70: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
4b80: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
4b90: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
4ba0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
4bb0: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
4bc0: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
4bd0: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
4be0: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
4bf0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
4c00: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
4c10: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
4c20: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
4c30: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
4c40: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
4c50: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
4c60: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
4c70: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
4c80: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
4c90: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
4ca0: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
4cb0: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
4cc0: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
4cd0: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
4ce0: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
4cf0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
4d00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
4d10: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
4d20: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
4d30: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
4d40: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
4d50: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
4d60: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
4d70: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64   xWrite()..*/.#d
4d80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4d90: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
4da0: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
4db0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4dc0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
4dd0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
4de0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4df0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
4e00: 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64     0x00000004.#d
4e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4e20: 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20  AP_ATOMIC2K     
4e30: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
4e40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4e50: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
4e60: 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64     0x00000010.#d
4e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4e80: 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20  AP_ATOMIC8K     
4e90: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64     0x00000020.#d
4ea0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4eb0: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20  AP_ATOMIC16K    
4ec0: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
4ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4ee0: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
4ef0: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
4f00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4f10: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
4f20: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
4f30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4f40: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
4f50: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
4f60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
4f70: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
4f80: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0a 2f     0x00000400../
4f90: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
4fa0: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
4fb0: 6c 73 20 7b 48 31 30 32 35 30 7d 20 3c 48 31 31  ls {H10250} <H11
4fc0: 31 32 30 3e 20 3c 48 31 31 33 31 30 3e 0a 2a 2a  120> <H11310>.**
4fd0: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
4fe0: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
4ff0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
5000: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
5010: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
5020: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
5030: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
5040: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
5050: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
5060: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
5070: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
5080: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
5090: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
50a0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
50b0: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
50c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
50d0: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
50e0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
50f0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
5100: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
5110: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
5120: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
5130: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
5140: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
5150: 46 6c 61 67 73 20 7b 48 31 30 32 36 30 7d 20 3c  Flags {H10260} <
5160: 48 31 31 31 32 30 3e 0a 2a 2a 0a 2a 2a 20 57 68  H11120>.**.** Wh
5170: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5180: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5190: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
51a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
51b0: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
51c0: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
51d0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
51e0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
51f0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5200: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5210: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5220: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5230: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5240: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5250: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5260: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5270: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5280: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5290: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
52a0: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
52b0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
52c0: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
52d0: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
52e0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
52f0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5300: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5310: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5320: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5330: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5340: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
5350: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5360: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5370: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5380: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
53a0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
53b0: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
53c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
53d0: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
53e0: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
53f0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5400: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
5410: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5420: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5430: 20 46 69 6c 65 20 48 61 6e 64 6c 65 20 7b 48 31   File Handle {H1
5440: 31 31 31 30 7d 20 3c 53 32 30 31 31 30 3e 0a 2a  1110} <S20110>.*
5450: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
5460: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
5470: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
5480: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
5490: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
54a0: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
54b0: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
54c0: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
54d0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
54e0: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
54f0: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
5500: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
5510: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
5520: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
5530: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
5540: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
5550: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
5560: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
5570: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
5580: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
5590: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
55a0: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
55b0: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
55c0: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
55d0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
55e0: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
55f0: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
5600: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
5610: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
5620: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
5630: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
5640: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
5650: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
5660: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
5670: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
5680: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
5690: 62 6a 65 63 74 20 7b 48 31 31 31 32 30 7d 20 3c  bject {H11120} <
56a0: 53 32 30 31 31 30 3e 0a 2a 2a 0a 2a 2a 20 45 76  S20110>.**.** Ev
56b0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
56c0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
56d0: 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f  vfs] xOpen metho
56e0: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
56f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
5700: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
5710: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
5720: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
5730: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
5740: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
5750: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
5760: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
5770: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
5780: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
5790: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
57a0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
57b0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
57c0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
57d0: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
57e0: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
57f0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
5800: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65  *.** If the xOpe
5810: 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  n method sets th
5820: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
5830: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
5840: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
5850: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
5860: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
5870: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
5880: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
5890: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
58a0: 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65  he xOpen reporte
58b0: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
58c0: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
58d0: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
58e0: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
58f0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
5900: 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f  d xOpen.** is fo
5910: 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73  r the xOpen to s
5920: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
5930: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
5940: 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ment to NULL..**
5950: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
5960: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
5970: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
5980: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
5990: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
59a0: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
59b0: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
59c0: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
59d0: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
59e0: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
59f0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
5a00: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
5a10: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
5a20: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
5a30: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
5a40: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
5a50: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
5a60: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
5a70: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
5a80: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
5a90: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
5aa0: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
5ab0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
5ac0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
5ad0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
5ae0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
5af0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5b00: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
5b10: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
5b20: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
5b30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
5b40: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
5b50: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
5b60: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
5b70: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
5b80: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
5b90: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
5ba0: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
5bb0: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
5bc0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
5bd0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
5be0: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
5bf0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5c00: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
5c10: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
5c20: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
5c30: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
5c40: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
5c50: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
5c60: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
5c70: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
5c80: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
5c90: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
5ca0: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
5cb0: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
5cc0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
5cd0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
5ce0: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
5cf0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
5d00: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
5d10: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
5d20: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
5d30: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
5d40: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
5d50: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
5d60: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
5d70: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
5d80: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
5d90: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
5da0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
5db0: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
5dc0: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
5dd0: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
5de0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
5df0: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
5e00: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
5e10: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
5e20: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
5e30: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
5e40: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
5e50: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
5e60: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
5e70: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
5e80: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
5e90: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
5ea0: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
5eb0: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
5ec0: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
5ed0: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
5ee0: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
5ef0: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
5f00: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
5f10: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
5f20: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
5f30: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
5f40: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
5f50: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
5f60: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49   use..** A [SQLI
5f70: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
5f80: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  TE | list of opc
5f90: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
5fa0: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
5fb0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
5fc0: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
5fd0: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
5fe0: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
5ff0: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a  d use opcodes.**
6000: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30   greater than 10
6010: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c  0 to avoid confl
6020: 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  icts..**.** The 
6030: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65  xSectorSize() me
6040: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65  thod returns the
6050: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20   sector size of 
6060: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  the.** device th
6070: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65  at underlies the
6080: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74   file.  The sect
6090: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a  or size is the.*
60a0: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20  * minimum write 
60b0: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66  that can be perf
60c0: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69  ormed without di
60d0: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65  sturbing.** othe
60e0: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  r bytes in the f
60f0: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63  ile.  The xDevic
6100: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
6110: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
6120: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f  urns a bit vecto
6130: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68  r describing beh
6140: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a  aviors of the.**
6150: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69   underlying devi
6160: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce:.**.** <ul>.*
6170: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6180: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20  OCAP_ATOMIC].** 
6190: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
61a0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a  AP_ATOMIC512].**
61b0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
61c0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a  CAP_ATOMIC1K].**
61d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
61e0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a  CAP_ATOMIC2K].**
61f0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6200: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a  CAP_ATOMIC4K].**
6210: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6220: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a  CAP_ATOMIC8K].**
6230: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
6240: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a  CAP_ATOMIC16K].*
6250: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6260: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a  OCAP_ATOMIC32K].
6270: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6280: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d  IOCAP_ATOMIC64K]
6290: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
62a0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
62b0: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ND].** <li> [SQL
62c0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
62d0: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  TIAL].** </ul>.*
62e0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
62f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
6300: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6310: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
6320: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
6330: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
6340: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
6350: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
6360: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
6370: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
6380: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
6390: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
63a0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
63b0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
63c0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
63d0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
63e0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
63f0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6400: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
6410: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
6420: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
6430: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
6440: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
6450: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
6460: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
6470: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
6480: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
6490: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
64a0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
64b0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
64c0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
64d0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
64e0: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
64f0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
6500: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
6510: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
6520: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
6530: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
6540: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
6550: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
6560: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
6570: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
6580: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
6590: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
65a0: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
65b0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
65c0: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
65d0: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
65e0: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
65f0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
6600: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
6610: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
6620: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
6630: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
6640: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
6650: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
6660: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
6670: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
6680: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
6690: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
66a0: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
66b0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
66c0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
66d0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
66e0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
66f0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
6700: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
6710: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
6720: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
6730: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
6740: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
6750: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
6760: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
6770: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
6780: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
6790: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
67a0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
67b0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
67c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
67d0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
67e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
67f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
6800: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
6810: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
6820: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
6830: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
6840: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
6850: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
6860: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
6870: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
6880: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
6890: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
68a0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
68b0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
68c0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
68d0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
68e0: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
68f0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64 69 74  le*);.  /* Addit
6900: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
6910: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
6920: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
6930: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
6940: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
6950: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
6960: 65 73 20 7b 48 31 31 33 31 30 7d 20 3c 53 33 30  es {H11310} <S30
6970: 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  800>.**.** These
6980: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
6990: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
69a0: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
69b0: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
69c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
69d0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
69e0: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
69f0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
6a00: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
6a10: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
6a20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6a30: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
6a40: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
6a50: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
6a60: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
6a70: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
6a80: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
6a90: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
6aa0: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
6ab0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
6ac0: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
6ad0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
6ae0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
6af0: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
6b00: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
6b10: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
6b20: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
6b30: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
6b40: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
6b50: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
6b60: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
6b70: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
6b80: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
6b90: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
6ba0: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
6bb0: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
6bc0: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23  is defined..*/.#
6bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
6be0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
6bf0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
6c00: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
6c10: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23  OXYFILE      2.#
6c20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
6c30: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
6c40: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6c50: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
6c60: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a               4..
6c70: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6c80: 4d 75 74 65 78 20 48 61 6e 64 6c 65 20 7b 48 31  Mutex Handle {H1
6c90: 37 31 31 30 7d 20 3c 53 32 30 31 33 30 3e 0a 2a  7110} <S20130>.*
6ca0: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
6cb0: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
6cc0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
6cd0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
6ce0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
6cf0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
6d00: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
6d10: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
6d20: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
6d30: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
6d40: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
6d50: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
6d60: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
6d70: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
6d80: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
6d90: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
6da0: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
6db0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
6dc0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
6dd0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
6de0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
6df0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
6e00: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
6e10: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
6e20: 66 61 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 31  face Object {H11
6e30: 31 34 30 7d 20 3c 53 32 30 31 30 30 3e 0a 2a 2a  140} <S20100>.**
6e40: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
6e50: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
6e60: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
6e70: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
6e80: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
6e90: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
6ea0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
6eb0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
6ec0: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
6ed0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
6ee0: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
6ef0: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
6f00: 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20   system"..**.** 
6f10: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
6f20: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
6f30: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
6f40: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
6f50: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
6f60: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
6f70: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
6f80: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
6f90: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
6fa0: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
6fb0: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
6fc0: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
6fd0: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
6fe0: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
6ff0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7000: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
7010: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
7020: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
7030: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
7040: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
7050: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
7060: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
7070: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
7080: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
7090: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
70a0: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
70b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
70c0: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
70d0: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
70e0: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
70f0: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
7100: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
7110: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
7120: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
7130: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
7140: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
7150: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
7160: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
7170: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
7180: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
7190: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
71a0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
71b0: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
71c0: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
71d0: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
71e0: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
71f0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
7200: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
7210: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
7220: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
7230: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
7240: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
7250: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
7260: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
7270: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
7280: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
7290: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
72a0: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
72b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
72c0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
72d0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
72e0: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
72f0: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
7300: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
7310: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
7320: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
7330: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
7340: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
7350: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
7360: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
7370: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
7380: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
7390: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
73a0: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
73b0: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
73c0: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
73d0: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
73e0: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
73f0: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
7400: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
7410: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
7420: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  dules..**.** SQL
7430: 69 74 65 20 77 69 6c 6c 20 67 75 61 72 61 6e 74  ite will guarant
7440: 65 65 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  ee that the zFil
7450: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
7460: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
7470: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
7480: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
7490: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
74a0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 2e  xFullPathname().
74b0: 20 20 53 51 4c 69 74 65 20 66 75 72 74 68 65 72    SQLite further
74c0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
74d0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
74e0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
74f0: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
7500: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
7510: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
7520: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
7530: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
7540: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7550: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
7560: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
7570: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
7580: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
7590: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
75a0: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
75b0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
75c0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
75d0: 72 20 69 73 20 78 4f 70 65 6e 20 69 73 20 61 20  r is xOpen is a 
75e0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
75f0: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
7600: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
7610: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
7620: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 57 68 65  r the file.  Whe
7630: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
7640: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
7650: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
7660: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
7670: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
7680: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
7690: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
76a0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
76b0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
76c0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
76d0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
76e0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
76f0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
7700: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
7710: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
7720: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
7730: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
7740: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
7750: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
7760: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
7770: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
7780: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
7790: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
77a0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
77b0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
77c0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
77d0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
77e0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
77f0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
7800: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
7810: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
7820: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
7830: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51  be set..**.** SQ
7840: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
7850: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
7860: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
7870: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
7880: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
7890: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
78a0: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
78b0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
78c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
78d0: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
78e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
78f0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
7900: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
7910: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
7920: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
7930: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
7940: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7950: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
7960: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
7970: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
7980: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
7990: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
79a0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  JOURNAL].** </ul
79b0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  >.**.** The file
79c0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
79d0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
79e0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
79f0: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
7a00: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
7a10: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
7a20: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
7a30: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
7a40: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
7a50: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
7a60: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
7a70: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
7a80: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
7a90: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
7aa0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
7ab0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
7ac0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
7ad0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
7ae0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
7af0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
7b00: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
7b10: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
7b20: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
7b30: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
7b40: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
7b50: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
7b60: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
7b70: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
7b80: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
7b90: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
7ba0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
7bb0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
7bc0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
7bd0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
7be0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
7bf0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
7c00: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
7c10: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7c20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
7c30: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
7c40: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7c50: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
7c60: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
7c70: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
7c80: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
7c90: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
7ca0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
7cb0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
7cc0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 54 68 65   is closed.  The
7cd0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
7ce0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
7cf0: 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
7d00: 54 45 4d 50 20 20 64 61 74 61 62 61 73 65 73 2c  TEMP  databases,
7d10: 20 6a 6f 75 72 6e 61 6c 73 20 61 6e 64 20 66 6f   journals and fo
7d20: 72 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  r subjournals..*
7d30: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7d40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
7d50: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
7d60: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
7d70: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
7d80: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
7d90: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
7da0: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
7db0: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
7dc0: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
7dd0: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
7de0: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
7df0: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
7e00: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
7e10: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
7e20: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
7e30: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
7e40: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
7e50: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
7e60: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
7e70: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
7e80: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
7e90: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
7ea0: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
7eb0: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
7ec0: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
7ed0: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
7ee0: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
7ef0: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
7f00: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
7f10: 2a 20 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46  * At least szOsF
7f20: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
7f30: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
7f40: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
7f50: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
7f60: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
7f70: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
7f80: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
7f90: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
7fa0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
7fb0: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
7fc0: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
7fd0: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
7fe0: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
7ff0: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
8000: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
8010: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
8020: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
8030: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
8040: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
8050: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8060: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
8070: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
8080: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
8090: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
80a0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
80b0: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
80c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
80d0: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
80e0: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
80f0: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
8100: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
8110: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
8120: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
8130: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
8140: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
8150: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
8160: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
8170: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
8180: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
8190: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
81a0: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
81b0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
81c0: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
81d0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
81e0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
81f0: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
8200: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8210: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
8220: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
8230: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
8240: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
8250: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
8260: 72 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ry..**.** SQLite
8270: 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c   will always all
8280: 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d  ocate at least m
8290: 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65  xPathname+1 byte
82a0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74  s for the.** out
82b0: 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c  put buffer xFull
82c0: 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65  Pathname.  The e
82d0: 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65  xact size of the
82e0: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
82f0: 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64  * is also passed
8300: 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20   as a parameter 
8310: 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73  to both  methods
8320: 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20  . If the output 
8330: 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74  buffer.** is not
8340: 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b   large enough, [
8350: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
8360: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
8370: 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20  ned. Since this 
8380: 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73  is.** handled as
8390: 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62   a fatal error b
83a0: 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d  y SQLite, vfs im
83b0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
83c0: 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a  ould endeavor.**
83d0: 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73   to prevent this
83e0: 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61   by setting mxPa
83f0: 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66  thname to a suff
8400: 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76  iciently large v
8410: 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
8420: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78  xRandomness(), x
8430: 53 6c 65 65 70 28 29 2c 20 61 6e 64 20 78 43 75  Sleep(), and xCu
8440: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 6e 74 65  rrentTime() inte
8450: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
8460: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
8470: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
8480: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
8490: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
84a0: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
84b0: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
84c0: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
84d0: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
84e0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
84f0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
8500: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
8510: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
8520: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
8530: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
8540: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
8550: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
8560: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
8570: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
8580: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
8590: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
85a0: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
85b0: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
85c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
85d0: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
85e0: 6e 2e 20 20 54 68 65 20 78 43 75 72 72 65 6e 74  n.  The xCurrent
85f0: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
8600: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
8610: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
8620: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
8630: 65 20 61 6e 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  e and time..**.*
8640: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
8650: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
8660: 69 74 65 33 5f 76 66 73 3b 0a 73 74 72 75 63 74  ite3_vfs;.struct
8670: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
8680: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
8690: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
86a0: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
86b0: 75 6d 62 65 72 20 2a 2f 0a 20 20 69 6e 74 20 73  umber */.  int s
86c0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
86d0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
86e0: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
86f0: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
8700: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
8710: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
8720: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
8730: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
8740: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
8750: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
8760: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
8770: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
8780: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
8790: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
87a0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
87b0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
87c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
87d0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
87e0: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
87f0: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
8800: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
8810: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
8820: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
8830: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
8840: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
8850: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
8860: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
8870: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
8880: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
8890: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
88a0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
88b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
88c0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
88d0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
88e0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
88f0: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
8900: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8910: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
8920: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
8930: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
8940: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
8950: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
8960: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
8970: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
8980: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
8990: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
89a0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
89b0: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
89c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
89d0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
89e0: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
89f0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
8a00: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
8a10: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
8a20: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
8a30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
8a40: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
8a50: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
8a60: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
8a70: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
8a80: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
8a90: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
8aa0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
8ab0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
8ac0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
8ad0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
8ae0: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65  char *);.  /* Ne
8af0: 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  w fields may be 
8b00: 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75  appended in figu
8b10: 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68  re versions.  Th
8b20: 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20  e iVersion.  ** 
8b30: 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65  value will incre
8b40: 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68  ment whenever th
8b50: 69 73 20 68 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d  is happens. */.}
8b60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8b70: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
8b80: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
8b90: 68 6f 64 20 7b 48 31 31 31 39 30 7d 20 3c 48 31  hod {H11190} <H1
8ba0: 31 31 34 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  1140>.**.** Thes
8bb0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
8bc0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
8bd0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
8be0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
8bf0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
8c00: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
8c10: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 7b 45 4e 44  fs] object. {END
8c20: 7d 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  }  They determin
8c30: 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
8c40: 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
8c50: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
8c60: 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
8c70: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
8c80: 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
8c90: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
8ca0: 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
8cb0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
8cc0: 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
8cd0: 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
8ce0: 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
8cf0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
8d00: 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
8d10: 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 62 6f  r the file is bo
8d20: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
8d30: 77 72 69 74 61 62 6c 65 2e 0a 2a 2a 20 57 69 74  writable..** Wit
8d40: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
8d50: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
8d60: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
8d70: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
8d80: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
8d90: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
8da0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
8db0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
8dc0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
8dd0: 57 52 49 54 45 20 31 0a 23 64 65 66 69 6e 65 20  WRITE 1.#define 
8de0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
8df0: 41 44 20 20 20 20 20 20 32 0a 0a 2f 2a 0a 2a 2a  AD      2../*.**
8e00: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
8e10: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
8e20: 20 4c 69 62 72 61 72 79 20 7b 48 31 30 31 33 30   Library {H10130
8e30: 7d 20 3c 53 32 30 30 30 30 3e 3c 53 33 30 31 30  } <S20000><S3010
8e40: 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
8e50: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
8e60: 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
8e70: 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
8e80: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
8e90: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
8ea0: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
8eb0: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
8ec0: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
8ed0: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
8ee0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
8ef0: 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  ize()..**.** A c
8f00: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
8f10: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
8f20: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
8f30: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
8f40: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
8f50: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
8f60: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
8f70: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
8f80: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
8f90: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
8fa0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
8fb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
8fc0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
8fd0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
8fe0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
8ff0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 4f 6e 6c 79  hutdown().  Only
9000: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
9010: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
9020: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
9030: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
9040: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
9050: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
9060: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 0a  armless no-ops..
9070: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
9080: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9090: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
90a0: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
90b0: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
90c0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
90d0: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
90e0: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
90f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
9100: 20 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65   Only.** an effe
9110: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
9120: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9130: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
9140: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
9150: 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 20 74  ll other calls t
9160: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
9170: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
9180: 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  s no-ops..**.** 
9190: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
91a0: 67 73 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  gs, sqlite3_init
91b0: 69 61 6c 69 7a 65 28 29 20 73 68 61 6c 6c 20 69  ialize() shall i
91c0: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
91d0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
91e0: 69 6c 61 72 6c 79 2c 20 73 71 6c 69 74 65 33 5f  ilarly, sqlite3_
91f0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 73 68  shutdown().** sh
9200: 61 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  all invoke sqlit
9210: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
9220: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
9230: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
9240: 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
9250: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
9260: 73 73 2e 0a 2a 2a 20 49 66 20 66 6f 72 20 73 6f  ss..** If for so
9270: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
9280: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9290: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
92a0: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
92b0: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
92c0: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
92d0: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
92e0: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
92f0: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
9300: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
9310: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
9320: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
9330: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9340: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9350: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
9360: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9370: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
9380: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
9390: 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
93a0: 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
93b0: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
93c0: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
93d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
93e0: 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
93f0: 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
9400: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
9410: 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
9420: 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
9430: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
9440: 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
9450: 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
9460: 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
9470: 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
9480: 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
9490: 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
94a0: 2a 20 61 6c 72 65 61 64 79 2e 20 20 48 6f 77 65  * already.  Howe
94b0: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
94c0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
94d0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
94e0: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
94f0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
9500: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
9510: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
9520: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9530: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
9540: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
9550: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
9560: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9570: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
9580: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
9590: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
95a0: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
95b0: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
95c0: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
95d0: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
95e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
95f0: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
9600: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9610: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
9620: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
9630: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
9640: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
9650: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
9660: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
9670: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
9680: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
9690: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
96a0: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
96b0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
96c0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
96d0: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
96e0: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
96f0: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
9700: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
9710: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
9720: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
9730: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
9740: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
9750: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
9760: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
9770: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
9780: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
9790: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
97a0: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
97b0: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
97c0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
97d0: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
97e0: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
97f0: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
9800: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
9810: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
9820: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
9830: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
9840: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
9850: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
9860: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
9870: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
9880: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
9890: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
98a0: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
98b0: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
98c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
98d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
98e0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
98f0: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
9900: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
9910: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
9920: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
9930: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
9940: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
9950: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
9960: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
9970: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
9980: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
9990: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
99a0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
99b0: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
99c0: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
99d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
99e0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
99f0: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
9a00: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
9a10: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
9a20: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
9a30: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
9a40: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
9a50: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9a60: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
9a70: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
9a80: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
9a90: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
9aa0: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
9ab0: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
9ac0: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
9ad0: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
9ae0: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
9af0: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
9b00: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
9b10: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
9b20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
9b30: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
9b40: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
9b50: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
9b60: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
9b70: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
9b80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
9b90: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
9ba0: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
9bb0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
9bc0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
9bd0: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
9be0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
9bf0: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
9c00: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
9c10: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
9c20: 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
9c30: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
9c40: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
9c50: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
9c60: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
9c70: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
9c80: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
9c90: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
9ca0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
9cb0: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
9cc0: 62 72 61 72 79 20 7b 48 31 34 31 30 30 7d 20 3c  brary {H14100} <
9cd0: 53 32 30 30 30 30 3e 3c 53 33 30 32 30 30 3e 0a  S20000><S30200>.
9ce0: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
9cf0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
9d00: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
9d10: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
9d20: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
9d30: 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
9d40: 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
9d50: 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
9d60: 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
9d70: 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
9d80: 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
9d90: 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
9da0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
9db0: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
9dc0: 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
9dd0: 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
9de0: 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
9df0: 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
9e00: 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
9e10: 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
9e20: 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
9e30: 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
9e40: 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54  l needs..**.** T
9e50: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
9e60: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
9e70: 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e   not threadsafe.
9e80: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
9e90: 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65  n.** must insure
9ea0: 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
9eb0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
9ec0: 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
9ed0: 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
9ee0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
9ef0: 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
9f00: 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65  ng.  Furthermore
9f10: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
9f20: 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ().** may only b
9f30: 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20  e invoked prior 
9f40: 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69  to library initi
9f50: 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a  alization using.
9f60: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ** [sqlite3_init
9f70: 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  ialize()] or aft
9f80: 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b  er shutdown by [
9f90: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9fa0: 28 29 5d 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  ()]..** Note, ho
9fb0: 77 65 76 65 72 2c 20 74 68 61 74 20 73 71 6c 69  wever, that sqli
9fc0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
9fd0: 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
9fe0: 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
9ff0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
a000: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
a010: 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
a020: 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
a030: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
a040: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
a050: 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
a060: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
a070: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
a080: 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61  READ | configura
a090: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
a0a0: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
a0b0: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
a0c0: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
a0d0: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
a0e0: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
a0f0: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
a100: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c  ding on the [SQL
a110: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
a120: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67  ETHREAD | config
a130: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
a140: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
a150: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
a160: 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
a170: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
a180: 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
a190: 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
a1a0: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 49 66 20  LITE_OK]..** If 
a1b0: 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
a1c0: 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
a1d0: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
a1e0: 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
a1f0: 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
a200: 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
a210: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
a220: 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
a230: 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 34 31 30 33  ents:.** [H14103
a240: 5d 20 5b 48 31 34 31 30 36 5d 20 5b 48 31 34 31  ] [H14106] [H141
a250: 32 30 5d 20 5b 48 31 34 31 32 33 5d 20 5b 48 31  20] [H14123] [H1
a260: 34 31 32 36 5d 20 5b 48 31 34 31 32 39 5d 20 5b  4126] [H14129] [
a270: 48 31 34 31 33 32 5d 20 5b 48 31 34 31 33 35 5d  H14132] [H14135]
a280: 0a 2a 2a 20 5b 48 31 34 31 33 38 5d 20 5b 48 31  .** [H14138] [H1
a290: 34 31 34 31 5d 20 5b 48 31 34 31 34 34 5d 20 5b  4141] [H14144] [
a2a0: 48 31 34 31 34 37 5d 20 5b 48 31 34 31 35 30 5d  H14147] [H14150]
a2b0: 20 5b 48 31 34 31 35 33 5d 20 5b 48 31 34 31 35   [H14153] [H1415
a2c0: 36 5d 20 5b 48 31 34 31 35 39 5d 0a 2a 2a 20 5b  6] [H14159].** [
a2d0: 48 31 34 31 36 32 5d 20 5b 48 31 34 31 36 35 5d  H14162] [H14165]
a2e0: 20 5b 48 31 34 31 36 38 5d 0a 2a 2f 0a 53 51 4c   [H14168].*/.SQL
a2f0: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
a300: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e   int sqlite3_con
a310: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
a320: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a330: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
a340: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 20  se connections  
a350: 7b 48 31 34 32 30 30 7d 20 3c 53 32 30 30 30 30  {H14200} <S20000
a360: 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  >.** EXPERIMENTA
a370: 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  L.**.** The sqli
a380: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
a390: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
a3a0: 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
a3b0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
a3c0: 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
a3d0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
a3e0: 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
a3f0: 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
a400: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a410: 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
a420: 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
a430: 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
a440: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
a450: 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
a460: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
a470: 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20  ument).  The.** 
a480: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
a490: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
a4a0: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 69  n only be used i
a4b0: 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
a4c0: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
a4d0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
a4e0: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
a4f0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 0a 2a  lite3_open()],.*
a500: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
a510: 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65  6()], or [sqlite
a520: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 0a  3_open_v2()].  .
a530: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
a540: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
a550: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
a560: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
a570: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
a580: 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74 65 67   verb - an integ
a590: 65 72 20 63 6f 64 65 20 74 68 61 74 20 69 6e 64  er code that ind
a5a0: 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a 20 61  icates what.** a
a5b0: 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61  spect of the [da
a5c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
a5d0: 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66  n] is being conf
a5e0: 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65 20 6f  igured..** The o
a5f0: 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72 20 74  nly choice for t
a600: 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b 53 51  his value is [SQ
a610: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
a620: 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e 65 77  OKASIDE]..** New
a630: 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b 65 6c   verbs are likel
a640: 79 20 74 6f 20 62 65 20 61 64 64 65 64 20 69 6e  y to be added in
a650: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
a660: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 41   of SQLite..** A
a670: 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
a680: 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20 74 68  nts depend on th
a690: 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 52 65  e verb..**.** Re
a6a0: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
a6b0: 48 31 34 32 30 33 5d 20 5b 48 31 34 32 30 36 5d  H14203] [H14206]
a6c0: 20 5b 48 31 34 32 30 39 5d 20 5b 48 31 34 32 31   [H14209] [H1421
a6d0: 32 5d 20 5b 48 31 34 32 31 35 5d 0a 2a 2f 0a 53  2] [H14215].*/.S
a6e0: 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
a6f0: 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  AL int sqlite3_d
a700: 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
a710: 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
a720: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
a730: 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
a740: 69 6f 6e 20 52 6f 75 74 69 6e 65 73 20 7b 48 31  ion Routines {H1
a750: 30 31 35 35 7d 20 3c 53 32 30 31 32 30 3e 0a 2a  0155} <S20120>.*
a760: 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
a770: 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
a780: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
a790: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
a7a0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51  rface between SQ
a7b0: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d  Lite.** and low-
a7c0: 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
a7d0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
a7e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ..**.** This obj
a7f0: 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f  ect is used in o
a800: 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e  nly one place in
a810: 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65   the SQLite inte
a820: 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e  rface..** A poin
a830: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
a840: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
a850: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
a860: 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  t to.** [sqlite3
a870: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20  _config()] when 
a880: 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
a890: 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b  n option is.** [
a8a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
a8b0: 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45  LLOC] or [SQLITE
a8c0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
a8d0: 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61  C].  .** By crea
a8e0: 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65  ting an instance
a8f0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a   of this object.
a900: 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69  ** and passing i
a910: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
a920: 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
a930: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a  NFIG_MALLOC]).**
a940: 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72   during configur
a950: 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63  ation, an applic
a960: 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66  ation can specif
a970: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
a980: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
a990: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20  ation subsystem 
a9a0: 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73  for SQLite to us
a9b0: 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  e for all of its
a9c0: 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  .** dynamic memo
a9d0: 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  ry needs..**.** 
a9e0: 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65  Note that SQLite
a9f0: 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65   comes with seve
aa00: 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65  ral [built-in me
aa10: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d  mory allocators]
aa20: 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72  .** that are per
aa30: 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20  fectly adequate 
aa40: 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c  for the overwhel
aa50: 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66  ming majority of
aa60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
aa70: 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f   and that this o
aa80: 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73  bject is only us
aa90: 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d  eful to a tiny m
aaa0: 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  inority of appli
aab0: 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20  cations.** with 
aac0: 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f  specialized memo
aad0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
aae0: 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69  quirements.  Thi
aaf0: 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61  s object is.** a
ab00: 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20  lso used during 
ab10: 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74  testing of SQLit
ab20: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70  e in order to sp
ab30: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
ab40: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
ab50: 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69  llocator that si
ab60: 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f  mulates memory o
ab70: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e  ut-of-memory con
ab80: 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72  ditions in.** or
ab90: 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68  der to verify th
aba0: 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65  at SQLite recove
abb0: 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72  rs gracefully fr
abc0: 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69  om such.** condi
abd0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tions..**.** The
abe0: 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72   xMalloc and xFr
abf0: 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
ac00: 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
ac10: 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
ac20: 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
ac30: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
ac40: 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54   C library..** T
ac50: 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68  he xRealloc meth
ac60: 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  od must work lik
ac70: 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d  e realloc() from
ac80: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
ac90: 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74 68 20  library.** with 
aca0: 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20 74 68  the exception th
acb0: 61 74 20 69 66 20 74 68 65 20 73 65 63 6f 6e 64  at if the second
acc0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 52 65   argument to xRe
acd0: 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a  alloc is zero,.*
ace0: 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20  * xRealloc must 
acf0: 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20  be a no-op - it 
ad00: 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d  must not perform
ad10: 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20   any allocation 
ad20: 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69  or.** deallocati
ad30: 6f 6e 2e 20 20 53 51 4c 69 74 65 20 67 75 61 72  on.  SQLite guar
ad40: 61 6e 74 65 65 64 73 20 74 68 61 74 20 74 68 65  anteeds that the
ad50: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
ad60: 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20   to.** xRealloc 
ad70: 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75  is always a valu
ad80: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20  e returned by a 
ad90: 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52  prior call to xR
ada0: 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73  oundup..** And s
adb0: 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65 72 65  o in cases where
adc0: 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61 79 73   xRoundup always
add0: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69 74   returns a posit
ade0: 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78  ive number,.** x
adf0: 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66  Realloc can perf
ae00: 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73 20 74  orm exactly as t
ae10: 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72  he standard libr
ae20: 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  ary realloc() an
ae30: 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e  d.** still be in
ae40: 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69 74 68   compliance with
ae50: 20 74 68 69 73 20 73 70 65 63 69 66 69 63 61 74   this specificat
ae60: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  ion..**.** xSize
ae70: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
ae80: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
ae90: 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
aea0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
aeb0: 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
aec0: 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
aed0: 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
aee0: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
aef0: 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
af00: 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
af10: 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
af20: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
af30: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
af40: 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
af50: 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
af60: 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
af70: 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
af80: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
af90: 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
afa0: 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
afb0: 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
afc0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
afd0: 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
afe0: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
aff0: 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
b000: 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
b010: 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
b020: 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
b030: 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
b040: 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
b050: 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
b060: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
b070: 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
b080: 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
b090: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
b0a0: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
b0b0: 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
b0c0: 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
b0d0: 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
b0e0: 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
b0f0: 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
b100: 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
b110: 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
b120: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
b130: 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
b140: 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
b150: 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72  allocator.  (For
b160: 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
b170: 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
b180: 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
b190: 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
b1a0: 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
b1b0: 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
b1c0: 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
b1d0: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
b1e0: 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
b1f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
b200: 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
b210: 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
b220: 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
b230: 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
b240: 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
b250: 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
b260: 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
b270: 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
b280: 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
b290: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
b2a0: 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
b2b0: 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
b2c0: 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
b2d0: 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
b2e0: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
b2f0: 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
b300: 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
b310: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
b320: 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
b330: 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
b340: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b350: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
b360: 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
b370: 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
b380: 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
b390: 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
b3a0: 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
b3b0: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
b3c0: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
b3d0: 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
b3e0: 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
b3f0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
b400: 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
b410: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
b420: 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
b430: 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
b440: 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
b450: 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
b460: 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
b470: 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
b480: 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
b490: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
b4a0: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
b4b0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
b4c0: 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
b4d0: 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
b4e0: 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
b4f0: 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
b500: 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
b510: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
b520: 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
b530: 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
b540: 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
b550: 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
b560: 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
b570: 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
b580: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
b590: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
b5a0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
b5b0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
b5c0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
b5d0: 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
b5e0: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
b5f0: 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
b600: 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
b610: 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
b620: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
b630: 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
b640: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
b650: 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
b660: 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
b670: 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
b680: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
b690: 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
b6a0: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
b6b0: 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
b6c0: 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
b6d0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
b6e0: 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
b6f0: 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
b700: 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
b710: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
b720: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
b730: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
b740: 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
b750: 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
b760: 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
b770: 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
b780: 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
b790: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
b7a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
b7b0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
b7c0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
b7d0: 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
b7e0: 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
b7f0: 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
b800: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b810: 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
b820: 4f 70 74 69 6f 6e 73 20 7b 48 31 30 31 36 30 7d  Options {H10160}
b830: 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50   <S20000>.** EXP
b840: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
b850: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
b860: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
b870: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
b880: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
b890: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
b8a0: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
b8b0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
b8c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
b8d0: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
b8e0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
b8f0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
b900: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
b910: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
b920: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
b930: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
b940: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
b950: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
b960: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
b970: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
b980: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
b990: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
b9a0: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
b9b0: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
b9c0: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
b9d0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
b9e0: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
b9f0: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
ba00: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
ba10: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
ba20: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
ba30: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
ba40: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
ba50: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
ba60: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
ba70: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
ba80: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
ba90: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
baa0: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
bab0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
bac0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61  This option disa
bad0: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
bae0: 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
baf0: 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
bb00: 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
bb10: 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
bb20: 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
bb30: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
bb40: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
bb50: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
bb60: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
bb70: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
bb80: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 54   this option.  T
bb90: 68 69 73 20 6f 70 74 69 6f 6e 20 64 69 73 61 62  his option disab
bba0: 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
bbb0: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
bbc0: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
bbd0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
bbe0: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
bbf0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
bc00: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
bc10: 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
bc20: 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
bc30: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
bc40: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
bc50: 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
bc60: 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
bc70: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
bc80: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
bc90: 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
bca0: 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
bcb0: 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
bcc0: 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
bcd0: 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
bce0: 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
bcf0: 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
bd00: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
bd10: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
bd20: 20 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61    See the [threa
bd30: 64 69 6e 67 20 6d 6f 64 65 5d 0a 2a 2a 20 64 6f  ding mode].** do
bd40: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
bd50: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
bd60: 6d 61 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  mation.</dd>.**.
bd70: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
bd80: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
bd90: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
bda0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
bdb0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
bdc0: 6e 2e 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  n.  This option 
bdd0: 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
bde0: 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
bdf0: 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
be00: 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
be10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
be20: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
be30: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
be40: 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
be50: 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
be60: 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
be70: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
be80: 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
be90: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
bea0: 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
beb0: 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
bec0: 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
bed0: 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
bee0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
bef0: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
bf00: 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
bf10: 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
bf20: 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
bf30: 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
bf40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bf50: 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
bf60: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
bf70: 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
bf80: 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
bf90: 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
bfa0: 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  See the [threadi
bfb0: 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e  ng mode] documen
bfc0: 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
bfd0: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
bfe0: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
bff0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
c000: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
c010: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
c020: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
c030: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
c040: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
c050: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
c060: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
c070: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
c080: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
c090: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
c0a0: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
c0b0: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
c0c0: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
c0d0: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
c0e0: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
c0f0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c100: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
c110: 6e 74 6f 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  nto SQLite.</dd>
c120: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c130: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
c140: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OC</dt>.** <dd>T
c150: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c160: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
c170: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
c180: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
c190: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
c1a0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
c1b0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
c1c0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
c1d0: 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
c1e0: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
c1f0: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
c200: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
c210: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
c220: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 54 68 69 73  outines..** This
c230: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
c240: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
c250: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
c260: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
c270: 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
c280: 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
c290: 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
c2a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
c2b0: 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
c2c0: 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
c2d0: 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64 3e  or example.</dd>
c2e0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
c2f0: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
c300: 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  US</dt>.** <dd>T
c310: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
c320: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
c330: 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
c340: 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
c350: 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
c360: 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
c370: 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
c380: 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
c390: 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
c3a0: 61 74 69 73 74 69 63 73 2e 20 57 68 65 6e 20 64  atistics. When d
c3b0: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
c3c0: 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
c3d0: 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
c3e0: 0a 2a 2a 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  .** non-operatio
c3f0: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
c400: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
c410: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
c420: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
c430: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
c440: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
c450: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
c460: 68 65 61 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  heap_limit()].**
c470: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
c480: 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20  _status()].**   
c490: 3c 2f 75 6c 3e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  </ul>.** </dd>.*
c4a0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
c4b0: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f  CONFIG_SCRATCH</
c4c0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
c4d0: 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
c4e0: 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
c4f0: 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
c500: 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
c510: 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
c520: 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  y.  There are th
c530: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
c540: 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
c550: 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
c560: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
c570: 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
c580: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
c590: 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
c5a0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
c5b0: 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
c5c0: 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
c5d0: 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
c5e0: 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
c5f0: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
c600: 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
c610: 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
c620: 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54  ultiple of 16. T
c630: 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20  he sz parameter 
c640: 73 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20  should be a few 
c650: 62 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20  bytes.** larger 
c660: 74 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20  than the actual 
c670: 73 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65  scratch space re
c680: 71 75 69 72 65 64 20 64 75 65 20 74 6f 20 69 6e  quired due to in
c690: 74 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e  ternal overhead.
c6a0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
c6b0: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f  gument should po
c6c0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
c6d0: 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
c6e0: 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
c6f0: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
c700: 65 6d 6f 72 79 2e 0a 2a 2a 20 53 51 4c 69 74 65  emory..** SQLite
c710: 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72   will use no mor
c720: 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
c730: 63 68 20 62 75 66 66 65 72 20 61 74 20 6f 6e 63  ch buffer at onc
c740: 65 20 70 65 72 20 74 68 72 65 61 64 2c 20 73 6f  e per thread, so
c750: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
c760: 73 65 74 20 74 6f 20 74 68 65 20 65 78 70 65 63  set to the expec
c770: 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  ted maximum numb
c780: 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 20 20  er of threads.  
c790: 54 68 65 20 73 7a 0a 2a 2a 20 70 61 72 61 6d 65  The sz.** parame
c7a0: 74 65 72 20 73 68 6f 75 6c 64 20 62 65 20 36 20  ter should be 6 
c7b0: 74 69 6d 65 73 20 74 68 65 20 73 69 7a 65 20 6f  times the size o
c7c0: 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
c7d0: 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
c7e0: 2e 0a 2a 2a 20 53 63 72 61 74 63 68 20 62 75 66  ..** Scratch buf
c7f0: 66 65 72 73 20 61 72 65 20 75 73 65 64 20 61 73  fers are used as
c800: 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 74 72   part of the btr
c810: 65 65 20 62 61 6c 61 6e 63 65 20 6f 70 65 72 61  ee balance opera
c820: 74 69 6f 6e 2e 20 20 49 66 0a 2a 2a 20 54 68 65  tion.  If.** The
c830: 20 62 74 72 65 65 20 62 61 6c 61 6e 63 65 72 20   btree balancer 
c840: 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c  needs additional
c850: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
c860: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
c870: 62 79 0a 2a 2a 20 73 63 72 61 74 63 68 20 62 75  by.** scratch bu
c880: 66 66 65 72 73 20 6f 72 20 69 66 20 6e 6f 20 73  ffers or if no s
c890: 63 72 61 74 63 68 20 62 75 66 66 65 72 20 73 70  cratch buffer sp
c8a0: 61 63 65 20 69 73 20 73 70 65 63 69 66 69 65 64  ace is specified
c8b0: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
c8c0: 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
c8d0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 74 6f 20 6f  3_malloc()] to o
c8e0: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
c8f0: 20 69 74 20 6e 65 65 64 73 2e 3c 2f 64 64 3e 0a   it needs.</dd>.
c900: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
c910: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
c920: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
c930: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
c940: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
c950: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
c960: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
c970: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
c980: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
c990: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
c9a0: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
c9b0: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
c9c0: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
c9d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
c9e0: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
c9f0: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
ca00: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
ca10: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
ca20: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
ca30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
ca40: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
ca50: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
ca60: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
ca70: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
ca80: 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
ca90: 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
caa0: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
cab0: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
cac0: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
cad0: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
cae0: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
caf0: 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
cb00: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
cb10: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
cb20: 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
cb30: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
cb40: 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
cb50: 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
cb60: 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
cb70: 20 68 65 61 64 65 72 2e 20 20 54 68 65 20 70 61   header.  The pa
cb80: 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69  ge header size i
cb90: 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73  s 20 to 40 bytes
cba0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a   depending on.**
cbb0: 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74   the host archit
cbc0: 65 63 74 75 72 65 2e 20 20 49 74 20 69 73 20 68  ecture.  It is h
cbd0: 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
cbe0: 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
cbf0: 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b  emory,.** to mak
cc00: 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f  e sz a little to
cc10: 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69  o large.  The fi
cc20: 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
cc30: 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20  should point to 
cc40: 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66  an allocation of
cc50: 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
cc60: 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
cc70: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  ** SQLite will u
cc80: 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
cc90: 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
cca0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
ccb0: 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
ccc0: 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
ccd0: 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
cce0: 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
ccf0: 6f 20 63 61 63 68 65 2e 20 20 49 66 20 61 64 64  o cache.  If add
cd00: 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
cd10: 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
cd20: 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
cd30: 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
cd40: 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
cd50: 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
cd60: 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
cd70: 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
cd80: 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
cd90: 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
cda0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
cdb0: 20 6d 69 67 68 74 20 75 73 65 20 6f 6e 65 20 6f   might use one o
cdc0: 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 4e 20  r more of the N 
cdd0: 62 75 66 66 65 72 73 20 74 6f 20 68 6f 6c 64 20  buffers to hold 
cde0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75  .** memory accou
cdf0: 6e 74 69 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f  nting informatio
ce00: 6e 2e 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  n. The pointer i
ce10: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
ce20: 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
ce30: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
ce40: 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
ce50: 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
ce60: 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
ce70: 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
ce80: 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
ce90: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
cea0: 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
ceb0: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  dd>This option s
cec0: 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
ced0: 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
cee0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
cef0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20   use.** for all 
cf00: 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
cf10: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
cf20: 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68   needs beyond th
cf30: 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ose provided.** 
cf40: 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
cf50: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
cf60: 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  nd [SQLITE_CONFI
cf70: 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
cf80: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
cf90: 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38   arguments: An 8
cfa0: 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
cfb0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
cfc0: 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
cfd0: 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
cfe0: 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
cff0: 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
d000: 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
d010: 65 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72  e..** If the fir
d020: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
d030: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
d040: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
d050: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
d060: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
d070: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
d080: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
d090: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
d0a0: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
d0b0: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
d0c0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
d0d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
d0e0: 4c 4c 4f 43 5d 2e 20 20 49 66 20 74 68 65 0a 2a  LLOC].  If the.*
d0f0: 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
d100: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
d110: 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
d120: 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
d130: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
d140: 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
d150: 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
d160: 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
d170: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
d180: 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
d190: 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
d1a0: 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
d1b0: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
d1c0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
d1d0: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
d1e0: 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
d1f0: 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
d200: 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
d210: 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
d220: 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
d230: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
d240: 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a  efined.</dd>.**.
d250: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
d260: 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
d270: 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69  ** <dd>This opti
d280: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
d290: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
d2a0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
d2b0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
d2c0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
d2d0: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
d2e0: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
d2f0: 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
d300: 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
d310: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
d320: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
d330: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
d340: 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
d350: 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
d360: 51 4c 69 74 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  QLite.</dd>.**.*
d370: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d380: 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
d390: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70  >.** <dd>This op
d3a0: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
d3b0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
d3c0: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
d3d0: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
d3e0: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
d3f0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
d400: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
d410: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
d420: 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
d430: 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
d440: 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
d450: 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
d460: 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  tex routines..**
d470: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
d480: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
d490: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
d4a0: 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
d4b0: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
d4c0: 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
d4d0: 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
d4e0: 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
d4f0: 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
d500: 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
d510: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 3c 2f 64 64  for example.</dd
d520: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
d530: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
d540: 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
d550: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
d560: 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
d570: 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
d580: 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65  he default.** me
d590: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
d5a0: 6c 6f 6f 6b 61 73 69 64 65 20 6f 70 74 69 6d 69  lookaside optimi
d5b0: 7a 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 69 72  zation.  The fir
d5c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
d5d0: 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
d5e0: 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
d5f0: 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
d600: 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
d610: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
d620: 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
d630: 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
d640: 6e 65 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 6f  nection.  This o
d650: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
d660: 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
d670: 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
d680: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42    The [SQLITE_DB
d690: 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
d6a0: 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71  ].** verb to [sq
d6b0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
d6c0: 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
d6d0: 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
d6e0: 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
d6f0: 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
d700: 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
d710: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
d720: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
d730: 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
d740: 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  dd>This option t
d750: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
d760: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
d770: 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
d780: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
d790: 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  he_methods] obje
d7a0: 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
d7b0: 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69   specifies the i
d7c0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61  nterface.** to a
d7d0: 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
d7e0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
d7f0: 6e 2e 20 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  n.  SQLite makes
d800: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
d810: 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
d820: 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
d830: 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
d840: 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
d850: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
d860: 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f  NFIG_GETPCACHE</
d870: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  dt>.** <dd>This 
d880: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
d890: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
d8a0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
d8b0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  r to an.** [sqli
d8c0: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
d8d0: 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  ds] object.  SQL
d8e0: 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
d8f0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
d900: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
d910: 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
d920: 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
d930: 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
d940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
d950: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
d960: 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
d970: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
d980: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
d990: 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
d9a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
d9b0: 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
d9c0: 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
d9d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
d9e0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
d9f0: 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
da00: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
da10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
da20: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
da30: 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
da40: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
da50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
da60: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
da70: 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
da80: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
da90: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
daa0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
dab0: 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
dac0: 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
dad0: 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
dae0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
daf0: 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
db00: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
db10: 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
db20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
db30: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
db40: 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
db50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
db60: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
db70: 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
db80: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
db90: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
dba0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
dbb0: 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
dbc0: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
dbd0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
dbe0: 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
dbf0: 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
dc00: 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
dc10: 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
dc20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
dc30: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
dc40: 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
dc50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
dc60: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
dc70: 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71         14  /* sq
dc80: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
dc90: 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
dca0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
dcb0: 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
dcc0: 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
dcd0: 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f  e_methods* */../
dce0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
dcf0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
dd00: 69 6f 6e 73 20 7b 48 31 30 31 37 30 7d 20 3c 53  ions {H10170} <S
dd10: 32 30 30 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20000>.** EXPERI
dd20: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
dd30: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
dd40: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
dd50: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
dd60: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
dd70: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
dd80: 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
dd90: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
dda0: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
ddb0: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
ddc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
ddd0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
dde0: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
ddf0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
de00: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
de10: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
de20: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
de30: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
de40: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
de50: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
de60: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
de70: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
de80: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
de90: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
dea0: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
deb0: 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
dec0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
ded0: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
dee0: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
def0: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
df00: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
df10: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
df20: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
df30: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
df40: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
df50: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
df60: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
df70: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  E</dt>.** <dd>Th
df80: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
df90: 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
dfa0: 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
dfb0: 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
dfc0: 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
dfd0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
dfe0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
dff0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
e000: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
e010: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e020: 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
e030: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
e040: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
e050: 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
e060: 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66  to an memory buf
e070: 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
e080: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
e090: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
e0a0: 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 4e 55  gument may be NU
e0b0: 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
e0c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
e0d0: 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
e0e0: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
e0f0: 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
e100: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
e110: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
e120: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
e130: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
e140: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
e150: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 61   and the third a
e160: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
e170: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
e180: 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
e190: 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
e1a0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
e1b0: 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
e1c0: 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
e1d0: 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
e1e0: 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
e1f0: 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
e200: 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
e210: 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
e220: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
e230: 62 6f 75 6e 64 61 72 79 2e 20 20 49 66 20 74 68  boundary.  If th
e240: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
e250: 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  t is not.** a mu
e260: 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
e270: 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 20 72 6f  is internally ro
e280: 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
e290: 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a  e next smaller.*
e2a0: 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  * multiple of 8.
e2b0: 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
e2c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
e2d0: 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  SIDE]</dd>.**.**
e2e0: 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
e2f0: 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
e300: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
e310: 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
e320: 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a  t int */.../*.**
e330: 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
e340: 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
e350: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
e360: 65 73 20 7b 48 31 32 32 30 30 7d 20 3c 53 31 30  es {H12200} <S10
e370: 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  700>.**.** The s
e380: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
e390: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
e3a0: 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
e3b0: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
e3c0: 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
e3d0: 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
e3e0: 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 54 68 65  e of SQLite. The
e3f0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
e400: 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
e410: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
e420: 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
e430: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 63   compatibility c
e440: 6f 6e 73 69 64 65 72 61 74 69 6f 6e 73 2e 0a 2a  onsiderations..*
e450: 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
e460: 73 3a 0a 2a 2a 20 5b 48 31 32 32 30 31 5d 20 5b  s:.** [H12201] [
e470: 48 31 32 32 30 32 5d 0a 2a 2f 0a 69 6e 74 20 73  H12202].*/.int s
e480: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
e490: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
e4a0: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
e4b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
e4c0: 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
e4d0: 52 6f 77 69 64 20 7b 48 31 32 32 32 30 7d 20 3c  Rowid {H12220} <
e4e0: 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 45 61  S10700>.**.** Ea
e4f0: 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53  ch entry in an S
e500: 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20  QLite table has 
e510: 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
e520: 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
e530: 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
e540: 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
e550: 22 5d 2e 20 54 68 65 20 72 6f 77 69 64 20 69 73  "]. The rowid is
e560: 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
e570: 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
e580: 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
e590: 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
e5a0: 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
e5b0: 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
e5c0: 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
e5d0: 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
e5e0: 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
e5f0: 75 6d 6e 73 2e 20 49 66 0a 2a 2a 20 74 68 65 20  umns. If.** the 
e600: 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
e610: 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
e620: 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
e630: 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
e640: 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
e650: 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
e660: 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  wid..**.** This 
e670: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
e680: 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
e690: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
e6a0: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
e6b0: 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
e6c0: 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
e6d0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e6e0: 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
e6f0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
e700: 20 20 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66    If no successf
e710: 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
e720: 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
e730: 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
e740: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
e750: 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
e760: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 5b 49  ..**.** If an [I
e770: 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
e780: 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
e790: 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  then the [rowid]
e7a0: 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
e7b0: 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72  .** row is retur
e7c0: 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
e7d0: 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
e7e0: 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75  he trigger is ru
e7f0: 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
e800: 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
e810: 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
e820: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
e830: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
e840: 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
e850: 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
e860: 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74  ted before the t
e870: 72 69 67 67 65 72 20 66 69 72 65 64 2e 0a 2a 2a  rigger fired..**
e880: 0a 2a 2a 20 41 6e 20 5b 49 4e 53 45 52 54 5d 20  .** An [INSERT] 
e890: 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
e8a0: 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
e8b0: 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
e8c0: 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
e8d0: 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
e8e0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
e8f0: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
e900: 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
e910: 6e 65 2e 20 20 54 68 75 73 20 49 4e 53 45 52 54  ne.  Thus INSERT
e920: 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
e930: 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
e940: 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
e950: 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
e960: 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
e970: 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
e980: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
e990: 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
e9a0: 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
e9b0: 6f 6e 20 66 61 69 6c 73 2e 20 20 57 68 65 6e 20  on fails.  When 
e9c0: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
e9d0: 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
e9e0: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
e9f0: 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
ea00: 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
ea10: 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
ea20: 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
ea30: 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
ea40: 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
ea50: 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
ea60: 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
ea70: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
ea80: 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
ea90: 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
eaa0: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
eab0: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
eac0: 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
ead0: 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
eae0: 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
eaf0: 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
eb00: 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
eb10: 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
eb20: 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
eb30: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 52 65  d back..**.** Re
eb40: 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
eb50: 48 31 32 32 32 31 5d 20 5b 48 31 32 32 32 33 5d  H12221] [H12223]
eb60: 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
eb70: 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
eb80: 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
eb90: 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
eba0: 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
ebb0: 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
ebc0: 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
ebd0: 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
ebe0: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
ebf0: 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
ec00: 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
ec10: 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
ec20: 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
ec30: 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
ec40: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
ec50: 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
ec60: 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
ec70: 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
ec80: 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
ec90: 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
eca0: 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
ecb0: 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
ecc0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
ecd0: 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
ece0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
ecf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
ed00: 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
ed10: 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 20 7b   Rows Modified {
ed20: 48 31 32 32 34 30 7d 20 3c 53 31 30 36 30 30 3e  H12240} <S10600>
ed30: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
ed40: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
ed50: 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
ed60: 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
ed70: 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
ed80: 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
ed90: 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
eda0: 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
edb0: 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
edc0: 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
edd0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ede0: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
edf0: 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
ee00: 65 72 2e 0a 2a 2a 20 4f 6e 6c 79 20 63 68 61 6e  er..** Only chan
ee10: 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72  ges that are dir
ee20: 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20  ectly specified 
ee30: 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c  by the [INSERT],
ee40: 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72   [UPDATE],.** or
ee50: 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
ee60: 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ent are counted.
ee70: 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e    Auxiliary chan
ee80: 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a  ges caused by.**
ee90: 20 74 72 69 67 67 65 72 73 20 61 72 65 20 6e 6f   triggers are no
eea0: 74 20 63 6f 75 6e 74 65 64 2e 20 55 73 65 20 74  t counted. Use t
eeb0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
eec0: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
eed0: 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20 66 69 6e 64  ction.** to find
eee0: 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
eef0: 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 63  r of changes inc
ef00: 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
ef10: 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
ef20: 73 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 65 73  s..**.** Changes
ef30: 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
ef40: 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
ef50: 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
ef60: 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
ef70: 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
ef80: 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
ef90: 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
efa0: 64 2e 0a 2a 2a 0a 2a 2a 20 41 20 22 72 6f 77 20  d..**.** A "row 
efb0: 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
efc0: 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
efd0: 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
efe0: 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
eff0: 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
f000: 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
f010: 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
f020: 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
f030: 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
f040: 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45  ects of [REPLACE
f050: 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
f060: 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
f070: 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
f080: 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41  essing, [DROP TA
f090: 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20  BLE], or by any 
f0a0: 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
f0b0: 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
f0c0: 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
f0d0: 68 61 6e 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  hanges..**.** A 
f0e0: 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
f0f0: 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
f100: 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
f110: 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
f120: 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
f130: 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
f140: 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
f150: 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
f160: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
f170: 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
f180: 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
f190: 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
f1a0: 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
f1b0: 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
f1c0: 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
f1d0: 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
f1e0: 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
f1f0: 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
f200: 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
f210: 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
f220: 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
f230: 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
f240: 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
f250: 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
f260: 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
f270: 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
f280: 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
f290: 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
f2a0: 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
f2b0: 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
f2c0: 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
f2d0: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  t..**.** This fu
f2e0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
f2f0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72  he number of dir
f300: 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20  ect row changes 
f310: 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72  in the.** most r
f320: 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
f330: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20  DATE, or DELETE 
f340: 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
f350: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69   the same.** tri
f360: 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
f370: 0a 2a 2a 20 54 68 75 73 2c 20 77 68 65 6e 20 63  .** Thus, when c
f380: 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
f390: 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
f3a0: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
f3b0: 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
f3c0: 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
f3d0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
f3e0: 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
f3f0: 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
f400: 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
f410: 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 57  he top level.  W
f420: 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
f430: 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20  f a trigger,.** 
f440: 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
f450: 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20  ges() interface 
f460: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f  can be called to
f470: 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
f480: 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69   of.** changes i
f490: 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
f4a0: 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
f4b0: 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
f4c0: 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65   DELETE.** state
f4d0: 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
f4e0: 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65  body of the same
f4f0: 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77   trigger..** How
f500: 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72  ever, the number
f510: 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
f520: 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
f530: 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  es.** caused by 
f540: 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63  subtriggers sinc
f550: 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65  e those have the
f560: 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 0a  ir own context..
f570: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
f580: 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
f590: 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
f5a0: 65 72 66 61 63 65 20 61 6e 64 20 74 68 65 0a 2a  erface and the.*
f5b0: 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
f5c0: 20 70 72 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20   pragma]..**.** 
f5d0: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
f5e0: 20 5b 48 31 32 32 34 31 5d 20 5b 48 31 32 32 34   [H12241] [H1224
f5f0: 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  3].**.** If a se
f600: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
f610: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
f620: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
f630: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
f640: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
f650: 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
f660: 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
f670: 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
f680: 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
f690: 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
f6a0: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
f6b0: 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
f6c0: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
f6d0: 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
f6e0: 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
f6f0: 66 69 65 64 20 7b 48 31 32 32 36 30 7d 20 3c 53  fied {H12260} <S
f700: 31 30 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  10600>.**.** Thi
f710: 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
f720: 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
f730: 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
f740: 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c  sed by [INSERT],
f750: 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  .** [UPDATE] or 
f760: 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
f770: 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
f780: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f790: 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
f7a0: 2a 2a 20 54 68 65 20 63 6f 75 6e 74 20 69 6e 63  ** The count inc
f7b0: 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65  ludes all change
f7c0: 73 20 66 72 6f 6d 20 61 6c 6c 20 0a 2a 2a 20 5b  s from all .** [
f7d0: 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
f7e0: 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
f7f0: 74 73 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ts.  However,.**
f800: 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
f810: 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
f820: 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
f830: 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
f840: 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
f850: 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
f860: 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
f870: 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
f880: 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
f890: 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
f8a0: 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
f8b0: 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
f8c0: 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
f8d0: 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
f8e0: 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
f8f0: 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
f900: 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
f910: 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
f920: 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
f930: 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 54 68  e counted..** Th
f940: 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f  e changes are co
f950: 75 6e 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  unted as soon as
f960: 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
f970: 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
f980: 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 28  s.** completed (
f990: 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
f9a0: 6e 74 20 68 61 6e 64 6c 65 20 69 73 20 70 61 73  nt handle is pas
f9b0: 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
f9c0: 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
f9d0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
f9e0: 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ()])..**.** See 
f9f0: 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
fa00: 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
fa10: 65 72 66 61 63 65 20 61 6e 64 20 74 68 65 0a 2a  erface and the.*
fa20: 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
fa30: 20 70 72 61 67 6d 61 5d 2e 0a 2a 2a 0a 2a 2a 20   pragma]..**.** 
fa40: 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
fa50: 20 5b 48 31 32 32 36 31 5d 20 5b 48 31 32 32 36   [H12261] [H1226
fa60: 33 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  3].**.** If a se
fa70: 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
fa80: 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
fa90: 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
faa0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
fab0: 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
fac0: 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
fad0: 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
fae0: 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
faf0: 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
fb00: 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
fb10: 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
fb20: 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
fb30: 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
fb40: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fb50: 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
fb60: 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
fb70: 79 20 7b 48 31 32 32 37 30 7d 20 3c 53 33 30 35  y {H12270} <S305
fb80: 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  00>.**.** This f
fb90: 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
fba0: 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
fbb0: 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
fbc0: 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
fbd0: 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
fbe0: 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
fbf0: 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
fc00: 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
fc10: 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
fc20: 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
fc30: 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
fc40: 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
fc50: 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
fc60: 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
fc70: 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
fc80: 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
fc90: 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
fca0: 0a 2a 2a 20 49 74 20 69 73 20 73 61 66 65 20 74  .** It is safe t
fcb0: 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74  o call this rout
fcc0: 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61  ine from a threa
fcd0: 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  d different from
fce0: 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74   the.** thread t
fcf0: 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  hat is currently
fd00: 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74   running the dat
fd10: 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e  abase operation.
fd20: 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e    But it.** is n
fd30: 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  ot safe to call 
fd40: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
fd50: 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  h a [database co
fd60: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a  nnection] that.*
fd70: 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d  * is closed or m
fd80: 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72  ight close befor
fd90: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
fda0: 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a  upt() returns..*
fdb0: 2a 0a 2a 2a 20 49 66 20 61 6e 20 53 51 4c 20 6f  *.** If an SQL o
fdc0: 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
fdd0: 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
fde0: 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
fdf0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
fe00: 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
fe10: 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
fe20: 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
fe30: 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
fe40: 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
fe50: 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
fe60: 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
fe70: 0a 2a 2a 0a 2a 2a 20 41 6e 20 53 51 4c 20 6f 70  .**.** An SQL op
fe80: 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
fe90: 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
fea0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
feb0: 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 49  INTERRUPT]..** I
fec0: 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65  f the interrupte
fed0: 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  d SQL operation 
fee0: 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  is an INSERT, UP
fef0: 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
ff00: 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64  ** that is insid
ff10: 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  e an explicit tr
ff20: 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
ff30: 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73  the entire trans
ff40: 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62  action.** will b
ff50: 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
ff60: 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a  tomatically..**.
ff70: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
ff80: 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
ff90: 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
ffa0: 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
ffb0: 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
ffc0: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
ffd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ffe0: 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
fff0: 20 20 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74    Any new SQL st
10000 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
10010 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
10020 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
10030 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
10040 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
10050 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
10060 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
10070 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
10080 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
10090 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
100a0 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
100b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
100c0 28 29 20 63 61 6c 6c 2e 20 20 4e 65 77 20 53 51  () call.  New SQ
100d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
100e0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
100f0 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
10100 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
10110 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
10120 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
10130 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
10140 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
10150 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
10160 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
10170 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
10180 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
10190 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
101a0 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
101b0 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
101c0 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
101d0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
101e0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
101f0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
10200 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
10210 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 52  returns..**.** R
10220 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
10230 5b 48 31 32 32 37 31 5d 20 5b 48 31 32 32 37 32  [H12271] [H12272
10240 5d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ].**.** If the d
10250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10260 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
10270 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
10280 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
10290 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
102a0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
102b0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
102c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
102d0 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
102e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
102f0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
10300 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
10310 6f 6d 70 6c 65 74 65 20 7b 48 31 30 35 31 30 7d  omplete {H10510}
10320 20 3c 53 37 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70200>.**.** 
10330 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
10340 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
10350 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
10360 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
10370 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
10380 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
10390 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
103a0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
103b0 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
103c0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
103d0 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
103e0 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
103f0 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
10400 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
10410 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
10420 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
10430 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
10440 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
10450 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
10460 61 74 65 6d 65 6e 74 2e 20 20 41 20 73 74 61 74  atement.  A stat
10470 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
10480 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
10490 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
104a0 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
104b0 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
104c0 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
104d0 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
104e0 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
104f0 6d 65 6e 74 2e 20 20 53 65 6d 69 63 6f 6c 6f 6e  ment.  Semicolon
10500 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
10510 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
10520 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
10530 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
10540 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
10550 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
10560 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
10570 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
10580 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
10590 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
105a0 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
105b0 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
105c0 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
105d0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
105e0 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e  Whitespace.** an
105f0 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20  d comments that 
10600 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c  follow the final
10610 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69   semicolon are i
10620 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  gnored..**.** Th
10630 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
10640 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
10650 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
10660 6c 65 74 65 2e 20 20 49 66 20 61 0a 2a 2a 20 6d  lete.  If a.** m
10670 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10680 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
10690 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
106a0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
106b0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
106c0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
106d0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
106e0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
106f0 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
10700 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
10710 0a 2a 2a 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65  .**.** If SQLite
10720 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
10730 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
10740 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
10750 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
10760 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
10770 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
10780 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
10790 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
107a0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
107b0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
107c0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
107d0 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
107e0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
107f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
10800 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
10810 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
10820 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
10830 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
10840 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
10850 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
10860 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 0a 2a  L is complete..*
10870 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
10880 73 3a 20 5b 48 31 30 35 31 31 5d 20 5b 48 31 30  s: [H10511] [H10
10890 35 31 32 5d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  512].**.** The i
108a0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
108b0 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
108c0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
108d0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
108e0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
108f0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
10900 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
10910 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
10920 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
10930 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
10940 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
10950 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
10960 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
10970 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74   char *sql);.int
10980 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
10990 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
109a0 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
109b0 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
109c0 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
109d0 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
109e0 20 45 72 72 6f 72 73 20 7b 48 31 32 33 31 30 7d   Errors {H12310}
109f0 20 3c 53 34 30 34 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S40400>.**.** 
10a00 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
10a10 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
10a20 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74  ction that might
10a30 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
10a40 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
10a50 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  pt is made to op
10a60 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  en a database ta
10a70 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72  ble that another
10a80 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
10a90 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64  ocess has locked
10aa0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 62  ..**.** If the b
10ab0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
10ac0 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
10ad0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
10ae0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
10af0 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
10b00 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
10b10 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
10b20 74 68 65 20 6c 6f 63 6b 2e 20 49 66 20 74 68 65  the lock. If the
10b30 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
10b40 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
10b50 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
10b60 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
10b70 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
10b80 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nts..**.** The f
10b90 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
10ba0 20 74 68 65 20 68 61 6e 64 6c 65 72 20 69 73 20   the handler is 
10bb0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
10bc0 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
10bd0 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
10be0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
10bf0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
10c00 65 72 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  er().  The secon
10c10 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
10c20 20 74 68 65 20 68 61 6e 64 6c 65 72 20 63 61 6c   the handler cal
10c30 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d  lback is the num
10c40 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61  ber of times tha
10c50 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  t the busy handl
10c60 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69  er has.** been i
10c70 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20  nvoked for this 
10c80 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
10c90 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
10ca0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
10cb0 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
10cc0 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
10cd0 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
10ce0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
10cf0 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
10d00 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
10d10 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
10d20 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49 66   returned..** If
10d30 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
10d40 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
10d50 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
10d60 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
10d70 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
10d80 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
10d90 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
10da0 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
10db0 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
10dc0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
10dd0 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
10de0 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
10df0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
10e00 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
10e10 6e 74 65 6e 74 69 6f 6e 2e 20 49 66 20 53 51 4c  ntention. If SQL
10e20 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
10e30 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
10e40 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
10e50 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
10e60 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
10e70 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
10e80 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
10e90 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
10ea0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
10eb0 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
10ec0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
10ed0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
10ee0 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
10ef0 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
10f00 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
10f10 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
10f20 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
10f30 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
10f40 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
10f50 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
10f60 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
10f70 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
10f80 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
10f90 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
10fa0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
10fb0 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
10fc0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
10fd0 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
10fe0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
10ff0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
11000 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
11010 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
11020 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
11030 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
11040 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
11050 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
11060 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
11070 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
11080 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
11090 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
110a0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
110b0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
110c0 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
110d0 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
110e0 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
110f0 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
11100 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
11110 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
11120 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
11130 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
11140 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
11150 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ceed..**.** The 
11160 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
11170 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
11180 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
11190 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20  _BUSY] error is 
111a0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51  converted to [SQ
111b0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
111c0 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ED].** when SQLi
111d0 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64  te is in the mid
111e0 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74  dle of a large t
111f0 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65  ransaction where
11200 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e   all the.** chan
11210 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74  ges will not fit
11220 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
11230 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69  ory cache.  SQLi
11240 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61  te will.** alrea
11250 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56  dy hold a RESERV
11260 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64  ED lock on the d
11270 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75  atabase file, bu
11280 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f  t it needs.** to
11290 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f   promote this lo
112a0 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20  ck to EXCLUSIVE 
112b0 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73  so that it can s
112c0 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61  pill cache.** pa
112d0 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ges into the dat
112e0 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f  abase file witho
112f0 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75  ut harm to concu
11300 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73  rrent.** readers
11310 2e 20 20 49 66 20 69 74 20 69 73 20 75 6e 61 62  .  If it is unab
11320 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
11330 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
11340 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
11350 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
11360 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
11370 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
11380 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
11390 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
113a0 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
113b0 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
113c0 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
113d0 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
113e0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
113f0 4b 45 44 5d 2e 20 20 54 68 69 73 20 65 72 72 6f  KED].  This erro
11400 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
11410 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
11420 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
11430 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
11440 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
11450 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77  href="/cvstrac/w
11460 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
11470 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
11480 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
11490 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
114a0 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
114b0 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
114c0 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
114d0 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
114e0 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 63 61 6e  .**.** There can
114f0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
11500 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
11510 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
11520 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11530 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
11540 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
11550 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
11560 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
11570 65 74 20 68 61 6e 64 6c 65 72 2e 20 20 4e 6f 74  et handler.  Not
11580 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b  e that calling [
11590 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
115a0 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20  eout()].** will 
115b0 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61  also set or clea
115c0 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  r the busy handl
115d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75  er..**.** The bu
115e0 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  sy callback shou
115f0 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20  ld not take any 
11600 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f  actions which mo
11610 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61  dify the.** data
11620 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
11630 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
11640 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20   busy handler.  
11650 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
11660 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
11670 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
11680 2e 0a 2a 2a 20 0a 2a 2a 20 52 65 71 75 69 72 65  ..** .** Require
11690 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 33 31  ments:.** [H1231
116a0 31 5d 20 5b 48 31 32 33 31 32 5d 20 5b 48 31 32  1] [H12312] [H12
116b0 33 31 34 5d 20 5b 48 31 32 33 31 36 5d 20 5b 48  314] [H12316] [H
116c0 31 32 33 31 38 5d 0a 2a 2a 0a 2a 2a 20 41 20 62  12318].**.** A b
116d0 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
116e0 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
116f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11700 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
11710 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
11720 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
11730 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
11740 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
11750 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
11760 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
11770 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
11780 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
11790 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
117a0 74 20 7b 48 31 32 33 34 30 7d 20 3c 53 34 30 34  t {H12340} <S404
117b0 31 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  10>.**.** This r
117c0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
117d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
117e0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
117f0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
11800 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
11810 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
11820 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
11830 73 20 6c 6f 63 6b 65 64 2e 20 20 54 68 65 20 68  s locked.  The h
11840 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
11850 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
11860 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
11870 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
11880 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
11890 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
118a0 61 74 65 64 2e 20 7b 48 31 32 33 34 33 7d 20 41  ated. {H12343} A
118b0 66 74 65 72 20 22 6d 73 22 20 6d 69 6c 6c 69 73  fter "ms" millis
118c0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
118d0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
118e0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
118f0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
11900 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
11910 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
11920 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
11930 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
11940 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c 69 6e 67 20 74  .**.** Calling t
11950 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
11960 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
11970 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
11980 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
11990 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
119a0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ndlers..**.** Th
119b0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
119c0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
119d0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
119e0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
119f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
11a00 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f  any any given mo
11a10 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
11a20 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
11a30 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
11a40 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
11a50 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
11a60 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
11a70 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
11a80 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
11a90 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
11aa0 61 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  ared..**.** Requ
11ab0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
11ac0 32 33 34 31 5d 20 5b 48 31 32 33 34 33 5d 20 5b  2341] [H12343] [
11ad0 48 31 32 33 34 34 5d 0a 2a 2f 0a 69 6e 74 20 73  H12344].*/.int s
11ae0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
11af0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
11b00 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
11b10 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
11b20 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
11b30 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
11b40 20 7b 48 31 32 33 37 30 7d 20 3c 53 31 30 30 30   {H12370} <S1000
11b50 30 3e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  0>.**.** Definit
11b60 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
11b70 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
11b80 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
11b90 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
11ba0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
11bb0 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
11bc0 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
11bd0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
11be0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
11bf0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
11c00 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
11c10 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
11c20 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
11c30 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
11c40 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
11c50 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
11c60 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
11c70 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
11c80 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
11c90 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
11ca0 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
11cb0 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
11cc0 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
11cd0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
11ce0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
11cf0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
11d00 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
11d10 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
11d20 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
11d30 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
11d40 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
11d50 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
11d60 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
11d70 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
11d80 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
11d90 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
11da0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
11db0 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
11dc0 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
11dd0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
11de0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
11df0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
11e00 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
11e10 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
11e20 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
11e30 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
11e40 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
11e50 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
11e60 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
11e70 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
11e80 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
11e90 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
11ea0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
11eb0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
11ec0 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
11ed0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
11ee0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
11ef0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
11f00 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
11f10 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
11f20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
11f30 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
11f40 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
11f50 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
11f60 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
11f70 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
11f80 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e 20  )]..**.** As an 
11f90 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
11fa0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
11fb0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
11fc0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
11fd0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
11fe0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
11ff0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
12000 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
12010 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
12020 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
12030 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
12040 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
12050 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
12060 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
12070 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
12080 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
12090 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
120a0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
120b0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
120c0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
120d0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
120e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
120f0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
12100 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
12110 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
12120 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
12130 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
12140 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
12150 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
12160 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
12170 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
12180 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
12190 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
121a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
121b0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
121c0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
121d0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
121e0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
121f0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
12200 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
12210 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
12220 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
12230 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
12240 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
12250 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
12260 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
12270 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
12280 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
12290 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
122a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
122b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
122c0 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
122d0 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
122e0 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
122f0 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
12300 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
12310 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
12320 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
12330 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
12340 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 74 20   parameter.  It 
12350 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
12360 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
12370 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
12380 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
12390 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
123a0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
123b0 63 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ction has finish
123c0 65 64 20 75 73 69 6e 67 20 74 68 65 20 72 65 73  ed using the res
123d0 75 6c 74 2c 20 69 74 20 73 68 6f 75 6c 64 0a 2a  ult, it should.*
123e0 2a 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  * pass the point
123f0 65 72 20 74 6f 20 74 68 65 20 72 65 73 75 6c 74  er to the result
12400 20 74 61 62 6c 65 20 74 6f 20 73 71 6c 69 74 65   table to sqlite
12410 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
12420 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
12430 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
12440 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
12450 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
12460 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
12470 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
12480 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
12490 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
124a0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
124b0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
124c0 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
124d0 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
124e0 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
124f0 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
12500 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
12510 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
12520 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
12530 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
12540 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
12550 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69  e3_get_table() i
12560 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c  nterface is impl
12570 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61  emented as a wra
12580 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
12590 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e  sqlite3_exec()].
125a0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65    The sqlite3_ge
125b0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e  t_table() routin
125c0 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  e does not have 
125d0 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79  access.** to any
125e0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73   internal data s
125f0 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c  tructures of SQL
12600 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e  ite.  It uses on
12610 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a  ly the public.**
12620 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
12630 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63  ed here.  As a c
12640 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f  onsequence, erro
12650 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e  rs that occur in
12660 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20   the.** wrapper 
12670 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66  layer outside of
12680 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73   the internal [s
12690 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63  qlite3_exec()] c
126a0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72  all are not.** r
126b0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73  eflected in subs
126c0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
126d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
126e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
126f0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  errmsg()]..**.**
12700 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
12710 2a 20 5b 48 31 32 33 37 31 5d 20 5b 48 31 32 33  * [H12371] [H123
12720 37 33 5d 20 5b 48 31 32 33 37 34 5d 20 5b 48 31  73] [H12374] [H1
12730 32 33 37 36 5d 20 5b 48 31 32 33 37 39 5d 20 5b  2376] [H12379] [
12740 48 31 32 33 38 32 5d 0a 2a 2f 0a 69 6e 74 20 73  H12382].*/.int s
12750 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
12760 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
12770 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
12780 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
12790 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
127a0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
127b0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
127c0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
127d0 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
127e0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
127f0 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
12800 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
12810 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
12820 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
12830 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
12840 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
12850 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
12860 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
12870 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
12880 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
12890 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
128a0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
128b0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
128c0 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20  free_table(char 
128d0 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a  **result);../*.*
128e0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d  * CAPI3REF: Form
128f0 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69  atted String Pri
12900 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20  nting Functions 
12910 7b 48 31 37 34 30 30 7d 20 3c 53 37 30 30 30 30  {H17400} <S70000
12920 3e 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20  ><S20000>.**.** 
12930 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
12940 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
12950 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
12960 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
12970 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
12980 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
12990 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ary..**.** The s
129a0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
129b0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
129c0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
129d0 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
129e0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
129f0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
12a00 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
12a10 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
12a20 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
12a30 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
12a40 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
12a50 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
12a60 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
12a70 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65  Both routines re
12a80 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70  turn a.** NULL p
12a90 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74  ointer if [sqlit
12aa0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20  e3_malloc()] is 
12ab0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
12ac0 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d  te enough.** mem
12ad0 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
12ae0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
12af0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 73 71 6c 69 74  ..**.** In sqlit
12b00 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
12b10 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
12b20 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
12b30 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
12b40 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
12b50 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
12b60 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
12b70 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
12b80 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
12b90 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
12ba0 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
12bb0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
12bc0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
12bd0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
12be0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
12bf0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
12c00 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
12c10 6e 70 72 69 6e 74 66 28 29 2e 20 20 54 68 69 73  nprintf().  This
12c20 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
12c30 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
12c40 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
12c50 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
12c60 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
12c70 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
12c80 20 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20   Note also that 
12c90 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
12ca0 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
12cb0 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
12cc0 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
12cd0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
12ce0 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
12cf0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
12d00 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 20 20  to the buffer.  
12d10 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
12d20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
12d30 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
12d40 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
12d50 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
12d60 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
12d70 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
12d80 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12d90 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
12da0 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
12db0 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
12dc0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
12dd0 0a 2a 2a 20 41 73 20 6c 6f 6e 67 20 61 73 20 74  .** As long as t
12de0 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69  he buffer size i
12df0 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a  s greater than z
12e00 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70  ero, sqlite3_snp
12e10 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61  rintf().** guara
12e20 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62  ntees that the b
12e30 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20  uffer is always 
12e40 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
12e50 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70    The first.** p
12e60 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
12e70 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
12e80 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
12e90 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
12ea0 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
12eb0 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
12ec0 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
12ed0 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
12ee0 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
12ef0 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
12f00 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
12f10 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
12f20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
12f30 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
12f40 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
12f50 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
12f60 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
12f70 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
12f80 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
12f90 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
12fa0 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
12fb0 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
12fc0 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
12fd0 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
12fe0 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
12ff0 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ptions..**.** Th
13000 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
13010 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
13020 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
13030 20 61 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74   a null-terminat
13040 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
13050 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
13060 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
13070 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
13080 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
13090 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
130a0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
130b0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
130c0 6c 2e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  l.  By doubling 
130d0 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
130e0 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
130f0 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
13100 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
13110 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
13120 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
13130 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
13140 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
13150 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
13160 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
13170 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
13180 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
13190 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
131a0 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
131b0 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
131c0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
131d0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
131e0 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
131f0 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
13200 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
13210 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
13220 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
13230 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
13240 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
13250 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
13260 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
13270 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
13280 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
13290 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
132a0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
132b0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
132c0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
132d0 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
132e0 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
132f0 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
13300 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
13310 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
13320 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
13330 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
13340 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
13350 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
13360 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
13370 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
13380 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
13390 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
133a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
133b0 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
133c0 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
133d0 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
133e0 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
133f0 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
13400 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
13410 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
13420 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
13430 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
13440 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
13450 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
13460 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
13470 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
13480 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
13490 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
134a0 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
134b0 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
134c0 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
134d0 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
134e0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
134f0 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
13500 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
13510 2a 20 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  * The %Q option 
13520 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
13530 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
13540 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
13550 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
13560 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
13570 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
13580 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
13590 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
135a0 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
135b0 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
135c0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
135d0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
135e0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
135f0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 20   single quotes) 
13600 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20  in place of the 
13610 25 51 20 6f 70 74 69 6f 6e 2e 20 20 53 6f 2c 20  %Q option.  So, 
13620 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
13630 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
13640 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
13650 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
13660 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
13670 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
13680 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
13690 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
136a0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
136b0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
136c0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
136d0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
136e0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
136f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
13700 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
13710 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
13720 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
13730 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
13740 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
13750 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
13760 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
13770 2a 2a 0a 2a 2a 20 54 68 65 20 22 25 7a 22 20 66  **.** The "%z" f
13780 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
13790 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 20 6c   works exactly l
137a0 69 6b 65 20 22 25 73 22 20 77 69 74 68 20 74 68  ike "%s" with th
137b0 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
137c0 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
137d0 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
137e0 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
137f0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
13800 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
13810 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
13820 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
13830 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a 20 52 65 71   {END}.**.** Req
13840 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
13850 31 37 34 30 33 5d 20 5b 48 31 37 34 30 36 5d 20  17403] [H17406] 
13860 5b 48 31 37 34 30 37 5d 0a 2a 2f 0a 63 68 61 72  [H17407].*/.char
13870 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
13880 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
13890 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
138a0 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
138b0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
138c0 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
138d0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
138e0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
138f0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
13900 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
13910 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
13920 65 6d 20 7b 48 31 37 33 30 30 7d 20 3c 53 32 30  em {H17300} <S20
13930 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  000>.**.** The S
13940 51 4c 69 74 65 20 63 6f 72 65 20 20 75 73 65 73  QLite core  uses
13950 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75   these three rou
13960 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66  tines for all of
13970 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65   its own.** inte
13980 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rnal memory allo
13990 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43  cation needs. "C
139a0 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76  ore" in the prev
139b0 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a  ious sentence.**
139c0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
139d0 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  e operating-syst
139e0 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20  em specific VFS 
139f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
13a00 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20   The.** Windows 
13a10 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20  VFS uses native 
13a20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
13a30 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65  e() for some ope
13a40 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  rations..**.** T
13a50 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
13a60 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
13a70 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
13a80 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
13a90 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
13aa0 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
13ab0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
13ac0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 49   parameter..** I
13ad0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
13ae0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
13af0 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
13b00 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
13b10 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
13b20 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
13b30 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
13b40 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
13b50 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
13b60 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
13b70 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
13b80 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
13b90 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
13ba0 2a 2a 20 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  ** Calling sqlit
13bb0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
13bc0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
13bd0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
13be0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
13bf0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
13c00 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
13c10 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
13c20 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
13c30 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 54 68  t be reused.  Th
13c40 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  e sqlite3_free()
13c50 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61   routine is.** a
13c60 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c   no-op if is cal
13c70 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
13c80 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e  pointer.  Passin
13c90 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  g a NULL pointer
13ca0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  .** to sqlite3_f
13cb0 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73  ree() is harmles
13cc0 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20  s.  After being 
13cd0 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a  freed, memory.**
13ce0 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20   should neither 
13cf0 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74  be read nor writ
13d00 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69  ten.  Even readi
13d10 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72  ng previously fr
13d20 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69  eed.** memory mi
13d30 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20  ght result in a 
13d40 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75  segmentation fau
13d50 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  lt or other seve
13d60 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d  re error..** Mem
13d70 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20  ory corruption, 
13d80 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
13d90 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73  ault, or other s
13da0 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  evere error.** m
13db0 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73  ight result if s
13dc0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
13dd0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e   called with a n
13de0 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  on-NULL pointer 
13df0 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20  that.** was not 
13e00 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71  obtained from sq
13e10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
13e20 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
13e30 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  c()..**.** The s
13e40 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
13e50 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
13e60 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
13e70 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
13e80 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
13e90 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
13ea0 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  s, where N is th
13eb0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
13ec0 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f  meter.  The memo
13ed0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
13ee0 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74   be resized is t
13ef0 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
13f00 6d 65 74 65 72 2e 20 20 49 66 20 74 68 65 20 66  meter.  If the f
13f10 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
13f20 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
13f30 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
13f40 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
13f50 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
13f60 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
13f70 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
13f80 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
13f90 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
13fa0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
13fb0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
13fc0 20 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70   If the second p
13fd0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
13fe0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
13ff0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
14000 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
14010 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
14020 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
14030 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
14040 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
14050 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
14060 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
14070 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
14080 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14090 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
140a0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
140b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
140c0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
140d0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
140e0 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
140f0 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
14100 69 6c 61 62 6c 65 2e 0a 2a 2a 20 49 66 20 4d 20  ilable..** If M 
14110 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
14120 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
14130 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
14140 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
14150 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
14160 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
14170 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
14180 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
14190 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
141a0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
141b0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
141c0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
141d0 2a 2a 20 49 66 20 73 71 6c 69 74 65 33 5f 72 65  ** If sqlite3_re
141e0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
141f0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
14200 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
14210 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
14220 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65 6d 6f 72  .**.** The memor
14230 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
14240 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
14250 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
14260 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  oc().** is alway
14270 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
14280 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
14290 62 6f 75 6e 64 61 72 79 2e 20 7b 45 4e 44 7d 0a  boundary. {END}.
142a0 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  **.** The defaul
142b0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
142c0 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61   of the memory a
142d0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
142e0 74 65 6d 20 75 73 65 73 0a 2a 2a 20 74 68 65 20  tem uses.** the 
142f0 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
14300 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 70  c() and free() p
14310 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 73  rovided by the s
14320 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
14330 79 2e 0a 2a 2a 20 7b 48 31 37 33 38 32 7d 20 48  y..** {H17382} H
14340 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
14350 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14360 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
14370 5f 4d 45 4d 4f 52 59 5f 53 49 5a 45 3d 3c 69 3e  _MEMORY_SIZE=<i>
14380 4e 4e 4e 3c 2f 69 3e 20 43 20 70 72 65 70 72 6f  NNN</i> C prepro
14390 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 28 77 68  cessor macro (wh
143a0 65 72 65 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 0a 2a  ere <i>NNN</i>.*
143b0 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 29  * is an integer)
143c0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 72  , then SQLite cr
143d0 65 61 74 65 20 61 20 73 74 61 74 69 63 20 61 72  eate a static ar
143e0 72 61 79 20 6f 66 20 61 74 20 6c 65 61 73 74 0a  ray of at least.
143f0 2a 2a 20 3c 69 3e 4e 4e 4e 3c 2f 69 3e 20 62 79  ** <i>NNN</i> by
14400 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 20  tes in size and 
14410 75 73 65 73 20 74 68 61 74 20 61 72 72 61 79 20  uses that array 
14420 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64  for all of its d
14430 79 6e 61 6d 69 63 0a 2a 2a 20 6d 65 6d 6f 72 79  ynamic.** memory
14440 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
14450 73 2e 20 7b 45 4e 44 7d 20 20 41 64 64 69 74 69  s. {END}  Additi
14460 6f 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  onal memory allo
14470 63 61 74 6f 72 20 6f 70 74 69 6f 6e 73 0a 2a 2a  cator options.**
14480 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
14490 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
144a0 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
144b0 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
144c0 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
144d0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
144e0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
144f0 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
14500 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
14510 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
14520 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
14530 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
14540 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
14550 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
14560 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
14570 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
14580 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
14590 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
145a0 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
145b0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57  sed..**.** The W
145c0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
145d0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 73 0a  ace layer calls.
145e0 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
145f0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
14600 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
14610 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
14620 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
14630 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
14640 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
14650 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
14660 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
14670 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
14680 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
14690 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
146a0 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
146b0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
146c0 20 61 72 65 20 64 65 74 65 63 74 65 64 2c 20 62   are detected, b
146d0 75 74 0a 2a 2a 20 74 68 65 79 20 61 72 65 20 72  ut.** they are r
146e0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
146f0 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
14700 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
14710 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
14720 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
14730 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  ]..**.** Require
14740 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 33 30  ments:.** [H1730
14750 33 5d 20 5b 48 31 37 33 30 34 5d 20 5b 48 31 37  3] [H17304] [H17
14760 33 30 35 5d 20 5b 48 31 37 33 30 36 5d 20 5b 48  305] [H17306] [H
14770 31 37 33 31 30 5d 20 5b 48 31 37 33 31 32 5d 20  17310] [H17312] 
14780 5b 48 31 37 33 31 35 5d 20 5b 48 31 37 33 31 38  [H17315] [H17318
14790 5d 0a 2a 2a 20 5b 48 31 37 33 32 31 5d 20 5b 48  ].** [H17321] [H
147a0 31 37 33 32 32 5d 20 5b 48 31 37 33 32 33 5d 0a  17322] [H17323].
147b0 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
147c0 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
147d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
147e0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
147f0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
14800 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
14810 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
14820 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
14830 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
14840 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
14850 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
14860 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
14870 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
14880 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
14890 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
148a0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
148b0 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
148c0 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
148d0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
148e0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
148f0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
14900 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
14910 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
14920 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
14930 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
14940 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f  _malloc(int);.vo
14950 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
14960 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
14970 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
14980 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
14990 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
149a0 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
149b0 74 69 73 74 69 63 73 20 7b 48 31 37 33 37 30 7d  tistics {H17370}
149c0 20 3c 53 33 30 32 31 30 3e 0a 2a 2a 0a 2a 2a 20   <S30210>.**.** 
149d0 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20  SQLite provides 
149e0 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66  these two interf
149f0 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69  aces for reporti
14a00 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73  ng on the status
14a10 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
14a20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b  te3_malloc()], [
14a30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c  sqlite3_free()],
14a40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
14a50 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74  alloc()].** rout
14a60 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d  ines, which form
14a70 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65   the built-in me
14a80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14a90 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a  subsystem..**.**
14aa0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
14ab0 2a 20 5b 48 31 37 33 37 31 5d 20 5b 48 31 37 33  * [H17371] [H173
14ac0 37 33 5d 20 5b 48 31 37 33 37 34 5d 20 5b 48 31  73] [H17374] [H1
14ad0 37 33 37 35 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33  7375].*/.sqlite3
14ae0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
14af0 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
14b00 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
14b10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
14b20 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73  ighwater(int res
14b30 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  etFlag);../*.** 
14b40 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f  CAPI3REF: Pseudo
14b50 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47  -Random Number G
14b60 65 6e 65 72 61 74 6f 72 20 7b 48 31 37 33 39 30  enerator {H17390
14b70 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20000>.**.**
14b80 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
14b90 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
14ba0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
14bb0 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
14bc0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
14bd0 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
14be0 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
14bf0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
14c00 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
14c10 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
14c20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
14c30 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
14c40 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
14c50 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
14c60 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
14c70 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
14c80 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
14c90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
14ca0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
14cb0 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
14cc0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
14cd0 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
14ce0 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
14cf0 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
14d00 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
14d10 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
14d20 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
14d30 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
14d40 20 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   The first time 
14d50 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
14d60 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20  invoked (either 
14d70 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79  internally or by
14d80 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
14d90 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73  ion) the PRNG is
14da0 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61   seeded using ra
14db0 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
14dc0 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52  d.** from the xR
14dd0 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64  andomness method
14de0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
14df0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
14e00 6a 65 63 74 2e 0a 2a 2a 20 4f 6e 20 61 6c 6c 20  ject..** On all 
14e10 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
14e20 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
14e30 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
14e40 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
14e50 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
14e60 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
14e70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
14e80 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
14e90 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20  * method..**.** 
14ea0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
14eb0 20 5b 48 31 37 33 39 32 5d 0a 2a 2f 0a 76 6f 69   [H17392].*/.voi
14ec0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
14ed0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
14ee0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
14ef0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
14f00 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
14f10 6e 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32  n Callbacks {H12
14f20 35 30 30 7d 20 3c 53 37 30 31 30 30 3e 0a 2a 2a  500} <S70100>.**
14f30 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
14f40 20 72 65 67 69 73 74 65 72 73 20 61 20 61 75 74   registers a aut
14f50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
14f60 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
14f70 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
14f80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
14f90 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
14fa0 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
14fb0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
14fc0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
14fd0 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
14fe0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
14ff0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
15000 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
15010 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
15020 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
15030 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
15040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
15050 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
15060 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
15070 20 20 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20    At various.** 
15080 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
15090 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
150a0 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
150b0 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
150c0 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
150d0 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
150e0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
150f0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
15100 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
15110 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
15120 65 20 61 6c 6c 6f 77 65 64 2e 20 20 54 68 65 20  e allowed.  The 
15130 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15140 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
15150 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
15160 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
15170 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
15180 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
15190 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
151a0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
151b0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
151c0 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
151d0 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
151e0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
151f0 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
15200 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
15210 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
15220 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
15230 20 65 72 72 6f 72 2e 20 20 49 66 20 74 68 65 20   error.  If the 
15240 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15250 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
15260 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
15270 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
15280 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
15290 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
152a0 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
152b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
152c0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
152d0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
152e0 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
152f0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
15300 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
15310 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
15320 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
15330 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
15340 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
15350 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
15360 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
15370 20 6f 6b 2e 20 20 57 68 65 6e 20 74 68 65 20 63   ok.  When the c
15380 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
15390 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
153a0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
153b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
153c0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
153d0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
153e0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
153f0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
15400 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
15410 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
15420 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
15430 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 54 68 65  nied. .**.** The
15440 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15450 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
15460 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  er callback is a
15470 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69   copy of the thi
15480 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
15490 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  to the sqlite3_s
154a0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20  et_authorizer() 
154b0 69 6e 74 65 72 66 61 63 65 2e 20 54 68 65 20 73  interface. The s
154c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
154d0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
154e0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
154f0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
15500 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
15510 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
15520 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
15530 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
15540 72 69 7a 65 64 2e 20 54 68 65 20 74 68 69 72 64  rized. The third
15550 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
15560 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
15570 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
15580 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
15590 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
155a0 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
155b0 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
155c0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
155d0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
155e0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61 63 74 69  *.** If the acti
155f0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
15600 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
15610 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
15620 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
15630 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
15640 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
15650 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
15660 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
15670 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
15680 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
15690 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
156a0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
156b0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
156c0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
156d0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
156e0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
156f0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
15700 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
15710 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
15720 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
15730 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
15740 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
15750 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 49 66 20   a table..** If 
15760 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
15770 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
15780 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
15790 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
157a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
157b0 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
157c0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
157d0 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
157e0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
157f0 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
15800 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
15810 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
15820 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
15830 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
15840 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
15850 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
15860 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
15870 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
15880 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
15890 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
158a0 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
158b0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
158c0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
158d0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
158e0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
158f0 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
15900 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
15910 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
15920 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
15930 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
15940 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
15950 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
15960 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
15970 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
15980 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
15990 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
159a0 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
159b0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
159c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
159d0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
159e0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
159f0 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
15a00 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
15a10 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
15a20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
15a30 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
15a40 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
15a50 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
15a60 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
15a70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
15a80 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
15a90 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
15aa0 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
15ab0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
15ac0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
15ad0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
15ae0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
15af0 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
15b00 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
15b10 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
15b20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
15b30 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
15b40 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
15b50 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
15b60 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
15b70 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
15b80 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
15b90 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
15ba0 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
15bb0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
15bc0 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
15bd0 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
15be0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
15bf0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15c00 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
15c10 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
15c20 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
15c30 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
15c40 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
15c50 61 6c 6c 2e 20 20 44 69 73 61 62 6c 65 20 74 68  all.  Disable th
15c60 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
15c70 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
15c80 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
15c90 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
15ca0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
15cb0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
15cc0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
15cd0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
15ce0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
15cf0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
15d00 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15d10 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
15d20 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
15d30 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
15d40 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
15d50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
15d60 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
15d70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
15d80 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
15d90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
15da0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
15db0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
15dc0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
15dd0 2a 2a 20 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** When [sqlite3
15de0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
15df0 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
15e00 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
15e10 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
15e20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
15e30 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
15e40 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
15e50 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
15e60 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
15e70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15e80 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
15e90 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
15ea0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
15eb0 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
15ec0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
15ed0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
15ee0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ()]..**.** Note 
15ef0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
15f00 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
15f10 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
15f20 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
15f30 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
15f40 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
15f50 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
15f60 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
15f70 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
15f80 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
15f90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
15fa0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
15fb0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
15fc0 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
15fd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
15fe0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
15ff0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
16000 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
16010 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
16020 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2a  chema change..**
16030 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
16040 3a 0a 2a 2a 20 5b 48 31 32 35 30 31 5d 20 5b 48  :.** [H12501] [H
16050 31 32 35 30 32 5d 20 5b 48 31 32 35 30 33 5d 20  12502] [H12503] 
16060 5b 48 31 32 35 30 34 5d 20 5b 48 31 32 35 30 35  [H12504] [H12505
16070 5d 20 5b 48 31 32 35 30 36 5d 20 5b 48 31 32 35  ] [H12506] [H125
16080 30 37 5d 20 5b 48 31 32 35 31 30 5d 0a 2a 2a 20  07] [H12510].** 
16090 5b 48 31 32 35 31 31 5d 20 5b 48 31 32 35 31 32  [H12511] [H12512
160a0 5d 20 5b 48 31 32 35 32 30 5d 20 5b 48 31 32 35  ] [H12520] [H125
160b0 32 31 5d 20 5b 48 31 32 35 32 32 5d 0a 2a 2f 0a  21] [H12522].*/.
160c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
160d0 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
160e0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
160f0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
16100 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
16110 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
16120 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
16130 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
16140 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
16150 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
16160 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
16170 20 7b 48 31 32 35 39 30 7d 20 3c 48 31 32 35 30   {H12590} <H1250
16180 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  0>.**.** The [sq
16190 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
161a0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
161b0 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
161c0 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74  ion] must.** ret
161d0 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49  urn either [SQLI
161e0 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66  TE_OK] or one of
161f0 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74   these two const
16200 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a  ants in order.**
16210 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74   to signal SQLit
16220 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  e whether or not
16230 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70   the action is p
16240 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74  ermitted.  See t
16250 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
16260 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
16270 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d  authorizer docum
16280 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64  entation] for ad
16290 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
162a0 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66  rmation..*/.#def
162b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
162c0 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
162d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
162e0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
162f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16300 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
16310 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
16320 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
16330 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
16340 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
16350 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
16360 74 69 6f 6e 20 43 6f 64 65 73 20 7b 48 31 32 35  tion Codes {H125
16370 35 30 7d 20 3c 48 31 32 35 30 30 3e 0a 2a 2a 0a  50} <H12500>.**.
16380 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
16390 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
163a0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
163b0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
163c0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
163d0 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
163e0 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
163f0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
16400 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
16410 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16420 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
16430 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
16440 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
16450 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
16460 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
16470 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
16480 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
16490 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
164a0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
164b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
164c0 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
164d0 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
164e0 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
164f0 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
16500 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
16510 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
16520 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
16530 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
16540 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
16550 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
16560 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
16570 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
16580 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
16590 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
165a0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
165b0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
165c0 61 6d 65 74 65 72 2e 20 20 54 68 65 20 35 74 68  ameter.  The 5th
165d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
165e0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
165f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
16600 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
16610 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
16620 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
16630 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 20 20 54  f applicable.  T
16640 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
16650 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
16660 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
16670 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
16680 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
16690 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
166a0 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
166b0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
166c0 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
166d0 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
166e0 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
166f0 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
16700 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
16710 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
16720 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32 35 35 31  ents:.** [H12551
16730 5d 20 5b 48 31 32 35 35 32 5d 20 5b 48 31 32 35  ] [H12552] [H125
16740 35 33 5d 20 5b 48 31 32 35 35 34 5d 0a 2a 2f 0a  53] [H12554].*/.
16750 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
16760 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
16770 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
16780 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
16790 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
167a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
167b0 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
167c0 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
167d0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
167e0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
167f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
16800 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
16810 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
16820 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
16830 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
16840 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
16850 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
16860 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
16870 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
16880 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
16890 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
168a0 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
168b0 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
168c0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
168d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
168e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
168f0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
16900 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
16910 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
16920 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
16930 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
16940 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
16950 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
16960 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
16970 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16980 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
16990 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
169a0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
169b0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
169c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
169d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
169e0 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
169f0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
16a00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
16a10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16a20 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
16a30 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
16a40 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
16a50 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16a60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16a70 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
16a80 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
16a90 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
16aa0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
16ab0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
16ac0 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
16ad0 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
16ae0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
16af0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
16b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16b10 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
16b20 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
16b30 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
16b40 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
16b50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16b60 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
16b70 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
16b80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
16b90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
16ba0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16bb0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
16bc0 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
16bd0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
16be0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
16bf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16c00 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
16c10 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
16c20 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
16c30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
16c40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
16c50 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
16c60 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
16c70 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
16c80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
16c90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
16ca0 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
16cb0 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
16cc0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
16cd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
16ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
16cf0 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
16d00 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
16d10 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
16d20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
16d30 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
16d40 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
16d50 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
16d60 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
16d70 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
16d80 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
16d90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
16da0 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
16db0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
16dc0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
16dd0 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
16de0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
16df0 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
16e00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
16e10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
16e20 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
16e30 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
16e40 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
16e50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
16e60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
16e70 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
16e80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
16e90 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
16ea0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
16eb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
16ec0 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
16ed0 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
16ee0 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
16ef0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
16f00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
16f10 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
16f20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
16f30 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
16f40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
16f50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
16f60 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
16f70 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
16f80 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
16f90 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
16fa0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
16fb0 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
16fc0 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
16fd0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
16fe0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
16ff0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17000 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
17010 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
17020 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17030 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17040 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17050 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
17060 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
17070 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
17080 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
17090 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
170a0 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
170b0 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
170c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
170d0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
170e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
170f0 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
17100 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
17110 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
17120 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
17130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
17140 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
17150 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
17160 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
17170 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
17180 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17190 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
171a0 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
171b0 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
171c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
171d0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
171e0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48  ing Functions {H
171f0 31 32 32 38 30 7d 20 3c 53 36 30 34 30 30 3e 0a  12280} <S60400>.
17200 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
17210 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
17220 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
17230 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
17240 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
17250 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
17260 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
17270 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
17280 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
17290 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
172a0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
172b0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
172c0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
172d0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
172e0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
172f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
17300 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
17310 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
17320 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
17330 20 72 65 74 75 72 6e 73 20 61 20 55 54 46 2d 38   returns a UTF-8
17340 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
17350 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
17360 74 65 78 74 0a 2a 2a 20 61 73 20 74 68 65 20 73  text.** as the s
17370 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
17380 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
17390 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 61 6c    Additional cal
173a0 6c 62 61 63 6b 73 20 6f 63 63 75 72 0a 2a 2a 20  lbacks occur.** 
173b0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
173c0 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
173d0 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
173e0 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
173f0 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
17400 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
17410 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
17420 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
17430 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
17440 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
17450 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
17460 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20  e3_profile() is 
17470 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61  invoked.** as ea
17480 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ch SQL statement
17490 20 66 69 6e 69 73 68 65 73 2e 20 20 54 68 65 20   finishes.  The 
174a0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
174b0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
174c0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
174d0 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
174e0 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
174f0 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
17500 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
17510 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
17520 6f 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  o run..**.** Req
17530 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
17540 31 32 32 38 31 5d 20 5b 48 31 32 32 38 32 5d 20  12281] [H12282] 
17550 5b 48 31 32 32 38 33 5d 20 5b 48 31 32 32 38 34  [H12283] [H12284
17560 5d 20 5b 48 31 32 32 38 35 5d 20 5b 48 31 32 32  ] [H12285] [H122
17570 38 37 5d 20 5b 48 31 32 32 38 38 5d 20 5b 48 31  87] [H12288] [H1
17580 32 32 38 39 5d 0a 2a 2a 20 5b 48 31 32 32 39 30  2289].** [H12290
17590 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ].*/.SQLITE_EXPE
175a0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
175b0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
175c0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
175d0 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
175e0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
175f0 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
17600 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
17610 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
17620 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
17630 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
17640 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
17650 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
17660 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17670 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
17680 73 73 20 43 61 6c 6c 62 61 63 6b 73 20 7b 48 31  ss Callbacks {H1
17690 32 39 31 30 7d 20 3c 53 36 30 34 30 30 3e 0a 2a  2910} <S60400>.*
176a0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
176b0 65 20 63 6f 6e 66 69 67 75 72 65 73 20 61 20 63  e configures a c
176c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
176d0 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 65   - the.** progre
176e0 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d 20 74 68  ss callback - th
176f0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 70 65  at is invoked pe
17700 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
17710 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e 6e 69 6e  g long.** runnin
17720 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  g calls to [sqli
17730 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
17740 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
17750 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  d.** [sqlite3_ge
17760 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20 41 6e 20  t_table()].  An 
17770 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
17780 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
17790 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
177a0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
177b0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
177c0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 70 72  .**.** If the pr
177d0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
177e0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
177f0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
17800 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
17810 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
17820 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
17830 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
17840 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
17850 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
17860 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
17870 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
17880 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
17890 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
178a0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
178b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
178c0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
178d0 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
178e0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
178f0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
17900 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
17910 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
17920 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
17930 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
17940 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
17950 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
17960 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
17970 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
17980 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
17990 3a 0a 2a 2a 20 5b 48 31 32 39 31 31 5d 20 5b 48  :.** [H12911] [H
179a0 31 32 39 31 32 5d 20 5b 48 31 32 39 31 33 5d 20  12912] [H12913] 
179b0 5b 48 31 32 39 31 34 5d 20 5b 48 31 32 39 31 35  [H12914] [H12915
179c0 5d 20 5b 48 31 32 39 31 36 5d 20 5b 48 31 32 39  ] [H12916] [H129
179d0 31 37 5d 20 5b 48 31 32 39 31 38 5d 0a 2a 2a 0a  17] [H12918].**.
179e0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
179f0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
17a00 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
17a10 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
17a20 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
17a30 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
17a40 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
17a50 6f 6e 6e 65 63 74 69 6f 6e 20 7b 48 31 32 37 30  onnection {H1270
17a60 30 7d 20 3c 53 34 30 32 30 30 3e 0a 2a 2a 0a 2a  0} <S40200>.**.*
17a70 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
17a80 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
17a90 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68  database file wh
17aa0 6f 73 65 20 6e 61 6d 65 20 69 73 20 67 69 76 65  ose name is give
17ab0 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66 69 6c 65  n by the.** file
17ac0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 54  name argument. T
17ad0 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
17ae0 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65  ment is interpre
17af0 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72  ted as UTF-8 for
17b00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
17b10 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
17b20 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20  pen_v2() and as 
17b30 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
17b40 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64  tive byte.** ord
17b50 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  er for sqlite3_o
17b60 70 65 6e 31 36 28 29 2e 20 41 20 5b 64 61 74 61  pen16(). A [data
17b70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17b80 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c   handle is usual
17b90 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69  ly.** returned i
17ba0 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66  n *ppDb, even if
17bb0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
17bc0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65  .  The only exce
17bd0 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a  ption is that.**
17be0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e   if SQLite is un
17bf0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
17c00 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
17c10 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
17c20 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20  ject,.** a NULL 
17c30 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20  will be written 
17c40 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65  into *ppDb inste
17c50 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20  ad of a pointer 
17c60 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  to the [sqlite3]
17c70 0a 2a 2a 20 6f 62 6a 65 63 74 2e 20 49 66 20 74  .** object. If t
17c80 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
17c90 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
17ca0 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
17cb0 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
17cc0 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
17cd0 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
17ce0 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
17cf0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54   is returned.  T
17d00 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
17d10 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
17d20 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
17d30 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
17d40 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
17d50 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
17d60 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
17d70 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 2e  on of the error.
17d80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61 75  .**.** The defau
17d90 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20  lt encoding for 
17da0 74 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  the database wil
17db0 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a  l be UTF-8 if.**
17dc0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
17dd0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
17de0 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  v2() is called a
17df0 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20  nd.** UTF-16 in 
17e00 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  the native byte 
17e10 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33  order if sqlite3
17e20 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65  _open16() is use
17e30 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72  d..**.** Whether
17e40 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72   or not an error
17e50 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20   occurs when it 
17e60 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75  is opened, resou
17e70 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74  rces.** associat
17e80 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
17e90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17ea0 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20  ] handle should 
17eb0 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a  be released by.*
17ec0 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  * passing it to 
17ed0 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
17ee0 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20  ] when it is no 
17ef0 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e  longer required.
17f00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
17f10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74  e3_open_v2() int
17f20 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b  erface works lik
17f30 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
17f40 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
17f50 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61  it accepts two a
17f60 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65  dditional parame
17f70 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f  ters for additio
17f80 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f  nal control.** o
17f90 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61  ver the new data
17fa0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
17fb0 20 20 54 68 65 20 66 6c 61 67 73 20 70 61 72 61    The flags para
17fc0 6d 65 74 65 72 20 63 61 6e 20 74 61 6b 65 20 6f  meter can take o
17fd0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
17fe0 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
17ff0 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
18000 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
18010 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
18020 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20 5b  EN_NOMUTEX] or [
18030 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
18040 4d 55 54 45 58 5d 20 66 6c 61 67 73 3a 0a 2a 2a  MUTEX] flags:.**
18050 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
18060 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
18070 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  DONLY]</dt>.** <
18080 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
18090 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61  is opened in rea
180a0 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66  d-only mode.  If
180b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f   the database do
180c0 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64  es not.** alread
180d0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f  y exist, an erro
180e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
180f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53  dd>.**.** <dt>[S
18100 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
18110 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
18120 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
18130 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
18140 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
18150 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
18160 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
18170 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
18180 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
18190 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
181a0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
181b0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
181c0 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
181d0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
181e0 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
181f0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
18200 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 5b 53 51 4c  >.**.** <dt>[SQL
18210 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
18220 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
18230 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
18240 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
18250 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
18260 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
18270 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
18280 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69  eates it if.** i
18290 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
182a0 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
182b0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
182c0 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
182d0 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
182e0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
182f0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
18300 64 64 3e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  dd>.** </dl>.**.
18310 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
18320 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
18330 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
18340 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
18350 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
18360 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e  hown above or on
18370 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61  e of the combina
18380 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
18390 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69  e combined.** wi
183a0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
183b0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 6f 72 20  PEN_NOMUTEX] or 
183c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
183d0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 73 2c 0a 2a  LMUTEX] flags,.*
183e0 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
183f0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
18400 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
18410 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
18420 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
18430 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
18440 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
18450 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
18460 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
18470 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
18480 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
18490 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
184a0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
184b0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
184c0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
184d0 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  .  If the.** [SQ
184e0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
184f0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
18500 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
18510 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
18520 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
18530 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
18540 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
18550 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
18560 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
18570 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
18580 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
18590 72 74 2d 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 49  rt-time..**.** I
185a0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
185b0 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
185c0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
185d0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
185e0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
185f0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
18600 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68   connection.  Th
18610 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
18620 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
18630 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
18640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18650 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
18660 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
18670 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
18680 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
18690 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
186a0 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
186b0 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
186c0 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
186d0 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
186e0 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
186f0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
18700 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
18710 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
18720 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
18730 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
18740 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
18750 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
18760 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
18770 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
18780 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 6c 65  *.** If the file
18790 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
187a0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
187b0 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
187c0 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
187d0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
187e0 72 65 61 74 65 64 2e 20 20 54 68 69 73 20 70 72  reated.  This pr
187f0 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77  ivate database w
18800 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61  ill be.** automa
18810 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
18820 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64  as soon as the d
18830 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18840 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
18850 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
18860 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
18870 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
18880 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
18890 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
188a0 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
188b0 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
188c0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
188d0 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
188e0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
188f0 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
18900 75 73 65 2e 20 20 49 66 20 74 68 65 20 66 6f 75  use.  If the fou
18910 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
18920 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
18930 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  er then the defa
18940 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
18950 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  ] object is used
18960 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20  ..**.** <b>Note 
18970 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73  to Windows users
18980 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64  :</b>  The encod
18990 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65  ing used for the
189a0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
189b0 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  nt.** of sqlite3
189c0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
189d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75  te3_open_v2() mu
189e0 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74  st be UTF-8, not
189f0 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64   whatever.** cod
18a00 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74  epage is current
18a10 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c  ly defined.  Fil
18a20 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e  enames containin
18a30 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a  g international.
18a40 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75  ** characters mu
18a50 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
18a60 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74  to UTF-8 prior t
18a70 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69  o passing them i
18a80 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  nto.** sqlite3_o
18a90 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
18aa0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
18ab0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
18ac0 2a 2a 20 5b 48 31 32 37 30 31 5d 20 5b 48 31 32  ** [H12701] [H12
18ad0 37 30 32 5d 20 5b 48 31 32 37 30 33 5d 20 5b 48  702] [H12703] [H
18ae0 31 32 37 30 34 5d 20 5b 48 31 32 37 30 36 5d 20  12704] [H12706] 
18af0 5b 48 31 32 37 30 37 5d 20 5b 48 31 32 37 30 39  [H12707] [H12709
18b00 5d 20 5b 48 31 32 37 31 31 5d 0a 2a 2a 20 5b 48  ] [H12711].** [H
18b10 31 32 37 31 32 5d 20 5b 48 31 32 37 31 33 5d 20  12712] [H12713] 
18b20 5b 48 31 32 37 31 34 5d 20 5b 48 31 32 37 31 37  [H12714] [H12717
18b30 5d 20 5b 48 31 32 37 31 39 5d 20 5b 48 31 32 37  ] [H12719] [H127
18b40 32 31 5d 20 5b 48 31 32 37 32 33 5d 0a 2a 2f 0a  21] [H12723].*/.
18b50 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
18b60 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
18b70 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
18b80 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
18b90 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
18ba0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
18bb0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
18bc0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
18bd0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
18be0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
18bf0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
18c00 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
18c10 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
18c20 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
18c30 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
18c40 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
18c50 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
18c60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
18c70 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
18c80 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
18c90 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
18ca0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
18cb0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
18cc0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
18cd0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
18ce0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
18cf0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
18d00 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
18d10 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
18d20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
18d30 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
18d40 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
18d50 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
18d60 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 20 7b  s And Messages {
18d70 48 31 32 38 30 30 7d 20 3c 53 36 30 32 30 30 3e  H12800} <S60200>
18d80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
18d90 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
18da0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
18db0 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
18dc0 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
18dd0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
18de0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
18df0 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
18e00 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
18e10 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
18e20 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
18e30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
18e40 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
18e50 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
18e60 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
18e70 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
18e80 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
18e90 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
18ea0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
18eb0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
18ec0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
18ed0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
18ee0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
18ef0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
18f00 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
18f10 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
18f20 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
18f30 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
18f40 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
18f50 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
18f60 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bled..**.** The 
18f70 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
18f80 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72   and sqlite3_err
18f90 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45  msg16() return E
18fa0 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a  nglish-language.
18fb0 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73  ** text that des
18fc0 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
18fd0 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  , as either UTF-
18fe0 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70  8 or UTF-16 resp
18ff0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 4d 65 6d  ectively..** Mem
19000 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
19010 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
19020 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
19030 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
19040 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
19050 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
19060 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
19070 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
19080 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
19090 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
190a0 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
190b0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
190c0 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
190d0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
190e0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
190f0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  e functions..**.
19100 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
19110 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
19120 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
19130 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
19140 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
19150 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
19160 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
19170 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
19180 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
19190 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
191a0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
191b0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
191c0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
191d0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
191e0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
191f0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
19200 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
19210 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
19220 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
19230 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
19240 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
19250 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
19260 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
19270 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
19280 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19290 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
192a0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
192b0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
192c0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
192d0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
192e0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
192f0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
19300 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
19310 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
19320 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
19330 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
19340 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
19350 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
19360 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
19370 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
19380 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
19390 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
193a0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
193b0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
193c0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
193d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
193e0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
193f0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
19400 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
19410 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
19420 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  set..**.** Requi
19430 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 32  rements:.** [H12
19440 38 30 31 5d 20 5b 48 31 32 38 30 32 5d 20 5b 48  801] [H12802] [H
19450 31 32 38 30 33 5d 20 5b 48 31 32 38 30 37 5d 20  12803] [H12807] 
19460 5b 48 31 32 38 30 38 5d 20 5b 48 31 32 38 30 39  [H12808] [H12809
19470 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
19480 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
19490 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74   *db);.int sqlit
194a0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
194b0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
194c0 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
194d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
194e0 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  ite3*);.const vo
194f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
19500 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
19510 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19520 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
19530 62 6a 65 63 74 20 7b 48 31 33 30 30 30 7d 20 3c  bject {H13000} <
19540 48 31 33 30 31 30 3e 0a 2a 2a 20 4b 45 59 57 4f  H13010>.** KEYWO
19550 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
19560 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
19570 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
19580 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
19590 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
195a0 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
195b0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
195c0 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
195d0 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
195e0 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
195f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
19600 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
19610 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
19620 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
19630 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
19640 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
19650 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
19660 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
19670 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
19680 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
19690 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
196a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
196b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
196c0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
196d0 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
196e0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
196f0 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
19700 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
19710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
19720 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
19730 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
19740 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
19750 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
19760 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
19770 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
19780 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
19790 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
197a0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
197b0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
197c0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
197d0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
197e0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
197f0 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
19800 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
19810 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
19820 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
19830 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
19840 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
19850 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
19860 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
19870 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
19880 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
19890 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
198a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
198b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
198c0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 20 7b  un-time Limits {
198d0 48 31 32 37 36 30 7d 20 3c 53 32 30 36 30 30 3e  H12760} <S20600>
198e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
198f0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
19900 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
19910 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
19920 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
19930 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
19940 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
19950 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
19960 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
19970 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19980 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
19990 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
199a0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
199b0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
199c0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
199d0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
199e0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
199f0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
19a00 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
19a10 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
19a20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
19a30 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
19a40 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
19a50 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 54 68 65   construct.  The
19a60 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
19a70 73 20 74 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e  s the old limit.
19a80 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6e 65  .**.** If the ne
19a90 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
19aa0 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
19ab0 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
19ac0 6e 67 65 64 2e 0a 2a 2a 20 46 6f 72 20 74 68 65  nged..** For the
19ad0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
19ae0 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  of SQLITE_LIMIT_
19af0 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a  XYZ there is a .
19b00 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
19b10 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
19b20 2a 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69  * set by a compi
19b30 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f  le-time C prepro
19b40 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d  cessor macro nam
19b50 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  ed .** [limits |
19b60 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d   SQLITE_MAX_XYZ]
19b70 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
19b80 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
19b90 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
19ba0 4d 41 58 5f 22 2e 29 0a 2a 2a 20 41 74 74 65 6d  MAX_".).** Attem
19bb0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
19bc0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
19bd0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
19be0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
19bf0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
19c00 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 6c  the hard upper l
19c10 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 20  imit..**.** Run 
19c20 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
19c30 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
19c40 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
19c50 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
19c60 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
19c70 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
19c80 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
19c90 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
19ca0 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
19cb0 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
19cc0 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
19cd0 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
19ce0 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
19cf0 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
19d00 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
19d10 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
19d20 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
19d30 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
19d40 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
19d50 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
19d60 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
19d70 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
19d80 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
19d90 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
19da0 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
19db0 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
19dc0 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
19dd0 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
19de0 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
19df0 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
19e00 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
19e10 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
19e20 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
19e30 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
19e40 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
19e50 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
19e60 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
19e70 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
19e80 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
19e90 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
19ea0 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
19eb0 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
19ec0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
19ed0 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
19ee0 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
19ef0 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
19f00 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
19f10 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
19f20 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
19f30 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
19f40 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
19f50 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
19f60 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
19f70 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  eases..**.** Req
19f80 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
19f90 31 32 37 36 32 5d 20 5b 48 31 32 37 36 36 5d 20  12762] [H12766] 
19fa0 5b 48 31 32 37 36 39 5d 0a 2a 2f 0a 69 6e 74 20  [H12769].*/.int 
19fb0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
19fc0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
19fd0 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
19fe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
19ff0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
1a000 65 67 6f 72 69 65 73 20 7b 48 31 32 37 39 30 7d  egories {H12790}
1a010 20 3c 48 31 32 37 36 30 3e 0a 2a 2a 20 4b 45 59   <H12760>.** KEY
1a020 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
1a030 74 65 67 6f 72 79 7d 20 7b 6c 69 6d 69 74 20 63  tegory} {limit c
1a040 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
1a050 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
1a060 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
1a070 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
1a080 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
1a090 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
1a0a0 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
1a0b0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
1a0c0 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
1a0d0 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
1a0e0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
1a0f0 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
1a100 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
1a110 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
1a120 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
1a130 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
1a140 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
1a150 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
1a160 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
1a170 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1a180 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
1a190 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
1a1a0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
1a1b0 77 2e 3c 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  w.<dd>.**.** <dt
1a1c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
1a1d0 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
1a1e0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1a1f0 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
1a200 4c 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  L statement.</dd
1a210 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1a220 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
1a230 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a240 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1a250 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
1a260 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
1a270 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
1a280 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
1a290 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
1a2a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1a2b0 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1a2c0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
1a2d0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
1a2e0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
1a2f0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1a300 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
1a310 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1a320 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
1a330 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
1a340 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
1a350 73 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  sion.</dd>.**.**
1a360 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49   <dt>SQLITE_LIMI
1a370 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1a380 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1a390 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1a3a0 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1a3b0 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1a3c0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 0a 2a  tatement.</dd>.*
1a3d0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1a3e0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
1a3f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1a400 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1a410 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
1a420 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
1a430 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
1a440 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1a450 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1a460 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
1a470 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
1a480 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a  CTION_ARG</dt>.*
1a490 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1a4a0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  m number of argu
1a4b0 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74  ments on a funct
1a4c0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
1a4d0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1a4e0 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
1a4f0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1a500 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
1a510 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
1a520 61 74 61 62 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a  atabases].</dd>.
1a530 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1a540 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
1a550 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
1a560 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1a570 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
1a580 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
1a590 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
1a5a0 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
1a5b0 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  rators.</dd>.**.
1a5c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49  ** <dt>SQLITE_LI
1a5d0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1a5e0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
1a5f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1a600 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73 20  er of variables 
1a610 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1a620 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a 20  ent that can.** 
1a630 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 0a 2a  be bound.</dd>.*
1a640 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
1a650 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1a660 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
1a670 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
1a680 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1a690 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
1a6a0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
1a6b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1a6c0 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
1a6d0 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
1a6e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1a6f0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
1a700 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
1a710 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1a720 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1a730 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
1a740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1a750 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
1a760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
1a770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a780 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1a790 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
1a7a0 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
1a7b0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
1a7c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1a7d0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
1a7e0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
1a7f0 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
1a800 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
1a810 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1a820 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
1a830 20 20 20 39 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     9../*.** CAPI
1a840 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
1a850 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1a860 20 7b 48 31 33 30 31 30 7d 20 3c 53 31 30 30 30   {H13010} <S1000
1a870 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  0>.** KEYWORDS: 
1a880 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
1a890 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54  ompiler}.**.** T
1a8a0 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
1a8b0 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
1a8c0 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
1a8d0 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
1a8e0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
1a8f0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
1a900 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1a910 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1a920 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
1a930 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1a940 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
1a950 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
1a960 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1a970 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1a980 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1a990 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
1a9a0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1a9b0 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
1a9c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
1a9d0 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
1a9e0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
1a9f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
1aa00 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
1aa10 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
1aa20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
1aa30 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
1aa40 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
1aa50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
1aa60 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
1aa70 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
1aa80 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
1aa90 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
1aaa0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1aab0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1aac0 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
1aad0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
1aae0 20 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72   If the nByte ar
1aaf0 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
1ab00 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
1ab10 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1ab20 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
1ab30 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1ab40 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
1ab50 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
1ab60 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
1ab70 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
1ab80 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
1ab90 53 71 6c 2e 20 20 57 68 65 6e 20 6e 42 79 74 65  Sql.  When nByte
1aba0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
1abb0 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74  , the.** zSql st
1abc0 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74  ring ends at eit
1abd0 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c  her the first '\
1abe0 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27  000' or '\u0000'
1abf0 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a   character or.**
1ac00 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79   the nByte-th by
1ac10 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  te, whichever co
1ac20 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68  mes first. If th
1ac30 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a  e caller knows.*
1ac40 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c  * that the suppl
1ac50 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75  ied string is nu
1ac60 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68  l-terminated, th
1ac70 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d  en there is a sm
1ac80 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e  all.** performan
1ac90 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20  ce advantage to 
1aca0 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73  be gained by pas
1acb0 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61  sing an nByte pa
1acc0 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20  rameter that.** 
1acd0 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  is equal to the 
1ace0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
1acf0 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
1ad00 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
1ad10 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
1ad20 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73  terminator bytes
1ad30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 70 7a 54 61 69  ..**.** If pzTai
1ad40 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
1ad50 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
1ad60 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
1ad70 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
1ad80 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
1ad90 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
1ada0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1adb0 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
1adc0 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
1add0 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
1ade0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
1adf0 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
1ae00 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
1ae10 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
1ae20 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
1ae30 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
1ae40 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
1ae50 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
1ae60 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1ae70 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
1ae80 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1ae90 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 49 66 20  e3_step()].  If 
1aea0 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
1aeb0 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
1aec0 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 49  t.** to NULL.  I
1aed0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
1aee0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
1aef0 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
1af00 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
1af10 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
1af20 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
1af30 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
1af40 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
1af50 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
1af60 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
1af70 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
1af80 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
1af90 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1afa0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
1afb0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
1afc0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
1afd0 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
1afe0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4f 6e  e NULL..**.** On
1aff0 20 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54   success, [SQLIT
1b000 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
1b010 64 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  d, otherwise an 
1b020 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1b030 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1b040 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1b050 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c  are_v2() and sql
1b060 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1b070 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61  2() interfaces a
1b080 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65  re.** recommende
1b090 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72  d for all new pr
1b0a0 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20  ograms. The two 
1b0b0 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73  older interfaces
1b0c0 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a   are retained.**
1b0d0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1b0e0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75  ompatibility, bu
1b0f0 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64  t their use is d
1b100 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 49  iscouraged..** I
1b110 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
1b120 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
1b130 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
1b140 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
1b150 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
1b160 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
1b170 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
1b180 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
1b190 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
1b1a0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
1b1b0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
1b1c0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
1b1d0 76 65 20 61 20 64 69 66 66 65 72 65 6e 74 6c 79  ve a differently
1b1e0 20 69 6e 20 74 77 6f 20 77 61 79 73 3a 0a 2a 2a   in two ways:.**
1b1f0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1b200 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
1b210 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
1b220 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
1b230 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
1b240 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
1b250 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
1b260 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
1b270 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
1b280 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
1b290 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
1b2a0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
1b2b0 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
1b2c0 20 20 49 66 20 74 68 65 20 73 63 68 65 6d 61 20    If the schema 
1b2d0 68 61 73 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a  has changed in.*
1b2e0 2a 20 61 20 77 61 79 20 74 68 61 74 20 6d 61 6b  * a way that mak
1b2f0 65 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  es the statement
1b300 20 6e 6f 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64   no longer valid
1b310 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1b320 29 5d 20 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a  )] will still.**
1b330 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1b340 53 43 48 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e  SCHEMA].  But un
1b350 6c 69 6b 65 20 74 68 65 20 6c 65 67 61 63 79 20  like the legacy 
1b360 62 65 68 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54  behavior, [SQLIT
1b370 45 5f 53 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20  E_SCHEMA] is.** 
1b380 6e 6f 77 20 61 20 66 61 74 61 6c 20 65 72 72 6f  now a fatal erro
1b390 72 2e 20 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  r.  Calling [sql
1b3a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1b3b0 29 5d 20 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f  )] again will no
1b3c0 74 20 6d 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72  t make the.** er
1b3d0 72 6f 72 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f  ror go away.  No
1b3e0 74 65 3a 20 75 73 65 20 5b 73 71 6c 69 74 65 33  te: use [sqlite3
1b3f0 5f 65 72 72 6d 73 67 28 29 5d 20 74 6f 20 66 69  _errmsg()] to fi
1b400 6e 64 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f  nd the text.** o
1b410 66 20 74 68 65 20 70 61 72 73 69 6e 67 20 65 72  f the parsing er
1b420 72 6f 72 20 74 68 61 74 20 72 65 73 75 6c 74 73  ror that results
1b430 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53   in an [SQLITE_S
1b440 43 48 45 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a  CHEMA] return..*
1b450 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1b460 69 3e 0a 2a 2a 20 57 68 65 6e 20 61 6e 20 65 72  i>.** When an er
1b470 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
1b480 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
1b490 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
1b4a0 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
1b4b0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
1b4c0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
1b4d0 20 63 6f 64 65 73 5d 2e 20 20 54 68 65 20 6c 65   codes].  The le
1b4e0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
1b4f0 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
1b500 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
1b510 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
1b520 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
1b530 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
1b540 65 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75  e.** and you wou
1b550 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
1b560 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
1b570 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1b580 29 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  )] in order.** t
1b590 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
1b5a0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
1b5b0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
1b5c0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
1b5d0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
1b5e0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
1b5f0 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
1b600 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1b610 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
1b620 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
1b630 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
1b640 74 73 3a 0a 2a 2a 20 5b 48 31 33 30 31 31 5d 20  ts:.** [H13011] 
1b650 5b 48 31 33 30 31 32 5d 20 5b 48 31 33 30 31 33  [H13012] [H13013
1b660 5d 20 5b 48 31 33 30 31 34 5d 20 5b 48 31 33 30  ] [H13014] [H130
1b670 31 35 5d 20 5b 48 31 33 30 31 36 5d 20 5b 48 31  15] [H13016] [H1
1b680 33 30 31 39 5d 20 5b 48 31 33 30 32 31 5d 0a 2a  3019] [H13021].*
1b690 2a 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  *.*/.int sqlite3
1b6a0 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
1b6b0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1b6c0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1b6d0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1b6e0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1b6f0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1b700 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1b710 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1b720 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1b730 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1b740 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1b750 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1b760 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1b770 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1b780 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1b790 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1b7a0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1b7b0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1b7c0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1b7d0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1b7e0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
1b7f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1b800 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1b810 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1b820 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1b830 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1b840 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1b850 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1b860 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1b870 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1b880 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1b890 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1b8a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1b8b0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1b8c0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1b8d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1b8e0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1b8f0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1b900 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1b910 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1b920 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1b930 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
1b940 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1b950 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1b960 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1b970 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1b980 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1b990 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1b9a0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1b9b0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1b9c0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1b9d0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1b9e0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1b9f0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1ba00 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1ba10 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1ba20 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1ba30 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1ba40 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1ba50 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1ba60 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1ba70 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
1ba80 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1ba90 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1baa0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1bab0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1bac0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1bad0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1bae0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1baf0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1bb00 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1bb10 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1bb20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1bb30 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1bb40 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1bb50 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1bb60 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1bb70 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1bb80 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1bb90 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1bba0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
1bbb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1bbc0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
1bbd0 6e 74 20 53 51 4c 20 7b 48 31 33 31 30 30 7d 20  nt SQL {H13100} 
1bbe0 3c 48 31 33 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <H13000>.**.** T
1bbf0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
1bc00 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
1bc10 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
1bc20 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
1bc30 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
1bc40 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
1bc50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1bc60 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
1bc70 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
1bc80 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
1bc90 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
1bca0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
1bcb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1bcc0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  _v2()]..**.** Re
1bcd0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
1bce0 48 31 33 31 30 31 5d 20 5b 48 31 33 31 30 32 5d  H13101] [H13102]
1bcf0 20 5b 48 31 33 31 30 33 5d 0a 2a 2f 0a 63 6f 6e   [H13103].*/.con
1bd00 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1bd10 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
1bd20 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
1bd30 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
1bd40 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
1bd50 6c 75 65 20 4f 62 6a 65 63 74 20 7b 48 31 35 30  lue Object {H150
1bd60 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 20  00} <S20200>.** 
1bd70 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
1bd80 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1bd90 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
1bda0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
1bdb0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
1bdc0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
1bdd0 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
1bde0 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
1bdf0 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
1be00 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
1be10 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
1be20 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
1be30 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
1be40 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
1be50 6f 72 65 73 2e 20 56 61 6c 75 65 73 20 73 74 6f  ores. Values sto
1be60 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
1be70 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
1be80 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
1be90 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
1bea0 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
1beb0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
1bec0 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
1bed0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
1bee0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
1bef0 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
1bf00 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
1bf10 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
1bf20 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
1bf30 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1bf40 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
1bf50 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
1bf60 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
1bf70 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
1bf80 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1bf90 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
1bfa0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
1bfb0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
1bfc0 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
1bfd0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
1bfe0 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
1bff0 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
1c000 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1c010 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
1c020 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
1c030 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
1c040 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
1c050 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
1c060 78 20 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e  x is held.  A in
1c070 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
1c080 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
1c090 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1c0a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
1c0b0 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
1c0c0 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
1c0d0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1c0e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
1c0f0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
1c100 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
1c110 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
1c120 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
1c130 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
1c140 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
1c150 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
1c160 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
1c170 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
1c180 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
1c190 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
1c1a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
1c1b0 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
1c1c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
1c1d0 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
1c1e0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
1c1f0 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
1c200 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
1c210 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
1c220 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1c230 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
1c240 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
1c250 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
1c260 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
1c270 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
1c280 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
1c290 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
1c2a0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
1c2b0 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
1c2c0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
1c2d0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
1c2e0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
1c2f0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
1c300 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
1c310 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
1c320 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
1c330 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
1c340 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
1c350 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
1c360 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
1c370 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
1c380 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
1c390 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
1c3a0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
1c3b0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 54   protected..** T
1c3c0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
1c3d0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
1c3e0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
1c3f0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
1c400 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
1c410 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
1c420 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1c430 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
1c440 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
1c450 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
1c460 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
1c470 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
1c480 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
1c490 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
1c4a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
1c4b0 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
1c4c0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
1c4d0 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
1c4e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1c4f0 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
1c500 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
1c510 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
1c520 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
1c530 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
1c540 74 20 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 31  t Object {H16001
1c550 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
1c560 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
1c570 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
1c580 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
1c590 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
1c5a0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
1c5b0 74 20 6f 62 6a 65 63 74 2e 20 20 41 20 70 6f 69  t object.  A poi
1c5c0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
1c5d0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1c5e0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
1c5f0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1c600 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
1c610 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1c620 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
1c630 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1c640 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
1c650 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
1c660 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
1c670 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
1c680 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
1c690 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
1c6a0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
1c6b0 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
1c6c0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
1c6d0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
1c6e0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
1c6f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
1c700 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
1c710 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
1c720 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
1c730 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
1c740 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
1c750 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1c760 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1c770 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
1c780 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c790 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
1c7a0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
1c7b0 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d  tements {H13500}
1c7c0 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59   <S70300>.** KEY
1c7d0 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
1c7e0 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
1c7f0 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
1c800 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
1c810 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
1c820 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
1c830 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
1c840 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
1c850 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 53  }.**.** In the S
1c860 51 4c 20 73 74 72 69 6e 67 73 20 69 6e 70 75 74  QL strings input
1c870 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1c880 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
1c890 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
1c8a0 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
1c8b0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
1c8c0 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
1c8d0 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
1c8e0 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
1c8f0 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
1c900 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
1c910 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
1c920 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
1c930 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
1c940 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
1c950 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
1c960 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
1c970 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
1c980 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
1c990 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
1c9a0 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
1c9b0 72 69 63 20 69 64 65 6e 74 69 66 65 72 2e 20 20  ric identifer.  
1c9c0 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
1c9d0 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
1c9e0 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
1c9f0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
1ca00 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
1ca10 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
1ca20 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
1ca30 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1ca40 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
1ca50 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
1ca60 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1ca70 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
1ca80 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1ca90 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
1caa0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
1cab0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
1cac0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
1cad0 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
1cae0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1caf0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1cb00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
1cb10 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
1cb20 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
1cb30 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
1cb40 20 62 65 20 73 65 74 2e 0a 2a 2a 20 54 68 65 20   be set..** The 
1cb50 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
1cb60 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
1cb70 64 65 78 20 6f 66 20 31 2e 20 20 57 68 65 6e 20  dex of 1.  When 
1cb80 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
1cb90 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
1cba0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
1cbb0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
1cbc0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
1cbd0 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
1cbe0 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
1cbf0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
1cc00 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 54 68 65  currence..** The
1cc10 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
1cc20 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
1cc30 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
1cc40 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
1cc50 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1cc60 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
1cc70 66 20 64 65 73 69 72 65 64 2e 20 20 54 68 65 20  f desired.  The 
1cc80 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
1cc90 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
1cca0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
1ccb0 4e 4e 2e 0a 2a 2a 20 54 68 65 20 4e 4e 4e 20 76  NN..** The NNN v
1ccc0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
1ccd0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
1cce0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1ccf0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
1cd00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
1cd10 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
1cd20 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
1cd30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69  )..**.** The thi
1cd40 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
1cd50 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
1cd60 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1cd70 72 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 6f 73  r..**.** In thos
1cd80 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
1cd90 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
1cda0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
1cdb0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
1cdc0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
1cdd0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
1cde0 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
1cdf0 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
1ce00 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
1ce10 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
1ce20 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
1ce30 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1ce40 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  s..** If the fou
1ce50 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
1ce60 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c   negative, the l
1ce70 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
1ce80 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
1ce90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
1cea0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
1ceb0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
1cec0 2a 0a 2a 2a 20 54 68 65 20 66 69 66 74 68 20 61  *.** The fifth a
1ced0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1cee0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
1cef0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1cf00 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
1cf10 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
1cf20 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
1cf30 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
1cf40 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
1cf50 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
1cf60 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
1cf70 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 49 66  shed with it. If
1cf80 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
1cf90 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
1cfa0 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
1cfb0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
1cfc0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
1cfd0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
1cfe0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
1cff0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
1d000 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
1d010 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
1d020 72 65 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  reed..** If the 
1d030 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
1d040 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
1d050 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
1d060 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
1d070 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
1d080 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
1d090 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
1d0a0 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
1d0b0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1d0c0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1d0d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ns..**.** The sq
1d0e0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1d0f0 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
1d100 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
1d110 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
1d120 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
1d130 72 6f 65 73 2e 20 20 41 20 7a 65 72 6f 62 6c 6f  roes.  A zeroblo
1d140 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
1d150 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
1d160 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
1d170 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
1d180 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
1d190 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
1d1a0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
1d1b0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
1d1c0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
1d1d0 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
1d1e0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
1d1f0 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
1d200 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
1d210 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
1d220 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
1d230 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
1d240 2a 2a 20 41 20 6e 65 67 61 74 69 76 65 20 76 61  ** A negative va
1d250 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
1d260 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
1d270 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
1d280 4f 42 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  OB..**.** The sq
1d290 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1d2a0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
1d2b0 63 61 6c 6c 65 64 20 61 66 74 65 72 0a 2a 2a 20  called after.** 
1d2c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d2d0 5f 76 32 28 29 5d 20 28 61 6e 64 20 69 74 73 20  _v2()] (and its 
1d2e0 76 61 72 69 61 6e 74 73 29 20 6f 72 20 5b 73 71  variants) or [sq
1d2f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
1d300 6e 64 0a 2a 2a 20 62 65 66 6f 72 65 20 5b 73 71  nd.** before [sq
1d310 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1d320 2a 20 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e  * Bindings are n
1d330 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
1d340 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
1d350 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
1d360 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
1d370 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
1d380 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
1d390 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1d3a0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1d3b0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
1d3c0 72 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 20  r an error code 
1d3d0 69 66 0a 2a 2a 20 61 6e 79 74 68 69 6e 67 20 67  if.** anything g
1d3e0 6f 65 73 20 77 72 6f 6e 67 2e 20 20 5b 53 51 4c  oes wrong.  [SQL
1d3f0 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
1d400 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
1d410 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
1d420 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1d430 2e 20 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  .  [SQLITE_NOMEM
1d440 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1d450 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
1d460 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
1d470 53 45 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  SE] might be ret
1d480 75 72 6e 65 64 20 69 66 20 74 68 65 73 65 20 72  urned if these r
1d490 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
1d4a0 65 64 20 6f 6e 20 61 0a 2a 2a 20 76 69 72 74 75  ed on a.** virtu
1d4b0 61 6c 20 6d 61 63 68 69 6e 65 20 74 68 61 74 20  al machine that 
1d4c0 69 73 20 74 68 65 20 77 72 6f 6e 67 20 73 74 61  is the wrong sta
1d4d0 74 65 20 6f 72 20 77 68 69 63 68 20 68 61 73 20  te or which has 
1d4e0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 66 69 6e  already been fin
1d4f0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 44 65 74 65 63  alized..** Detec
1d500 74 69 6f 6e 20 6f 66 20 6d 69 73 75 73 65 20 69  tion of misuse i
1d510 73 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 41  s unreliable.  A
1d520 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
1d530 6c 64 20 6e 6f 74 20 64 65 70 65 6e 64 0a 2a 2a  ld not depend.**
1d540 20 6f 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53   on SQLITE_MISUS
1d550 45 20 72 65 74 75 72 6e 73 2e 20 20 53 51 4c 49  E returns.  SQLI
1d560 54 45 5f 4d 49 53 55 53 45 20 69 73 20 69 6e 74  TE_MISUSE is int
1d570 65 6e 64 65 64 20 74 6f 20 69 6e 64 69 63 61 74  ended to indicat
1d580 65 20 61 0a 2a 2a 20 61 20 6c 6f 67 69 63 20 65  e a.** a logic e
1d590 72 72 6f 72 20 69 6e 20 74 68 65 20 61 70 70 6c  rror in the appl
1d5a0 69 63 61 74 69 6f 6e 2e 20 20 46 75 74 75 72 65  ication.  Future
1d5b0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1d5c0 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 70 61 6e  ite might.** pan
1d5d0 69 63 20 72 61 74 68 65 72 20 74 68 61 6e 20 72  ic rather than r
1d5e0 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
1d5f0 55 53 45 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  USE..**.** See a
1d600 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1d610 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1d620 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
1d630 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1d640 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
1d650 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1d660 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1d670 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65  .**.** Requireme
1d680 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 35 30 36 5d  nts:.** [H13506]
1d690 20 5b 48 31 33 35 30 39 5d 20 5b 48 31 33 35 31   [H13509] [H1351
1d6a0 32 5d 20 5b 48 31 33 35 31 35 5d 20 5b 48 31 33  2] [H13515] [H13
1d6b0 35 31 38 5d 20 5b 48 31 33 35 32 31 5d 20 5b 48  518] [H13521] [H
1d6c0 31 33 35 32 34 5d 20 5b 48 31 33 35 32 37 5d 0a  13524] [H13527].
1d6d0 2a 2a 20 5b 48 31 33 35 33 30 5d 20 5b 48 31 33  ** [H13530] [H13
1d6e0 35 33 33 5d 20 5b 48 31 33 35 33 36 5d 20 5b 48  533] [H13536] [H
1d6f0 31 33 35 33 39 5d 20 5b 48 31 33 35 34 32 5d 20  13539] [H13542] 
1d700 5b 48 31 33 35 34 35 5d 20 5b 48 31 33 35 34 38  [H13545] [H13548
1d710 5d 20 5b 48 31 33 35 35 31 5d 0a 2a 2a 0a 2a 2f  ] [H13551].**.*/
1d720 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1d730 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
1d740 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1d750 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
1d760 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1d770 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1d780 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
1d790 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
1d7a0 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
1d7b0 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
1d7c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
1d7d0 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
1d7e0 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
1d7f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
1d800 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
1d810 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1d820 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
1d830 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
1d840 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
1d850 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1d860 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
1d870 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
1d880 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
1d890 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1d8a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1d8b0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
1d8c0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
1d8d0 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
1d8e0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
1d8f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1d900 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
1d910 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
1d920 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
1d930 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1d940 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
1d950 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1d960 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
1d970 61 72 61 6d 65 74 65 72 73 20 7b 48 31 33 36 30  arameters {H1360
1d980 30 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a  0} <S70300>.**.*
1d990 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63  * This routine c
1d9a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
1d9b0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
1d9c0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
1d9d0 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
1d9e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
1d9f0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
1da00 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
1da10 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
1da20 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
1da30 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
1da40 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
1da50 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
1da60 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
1da70 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
1da80 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
1da90 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
1daa0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
1dab0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ime..**.** This 
1dac0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
1dad0 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
1dae0 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
1daf0 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
1db00 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
1db10 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
1db20 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
1db30 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
1db40 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1db50 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
1db60 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
1db70 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 61 72  s of the ?NNN ar
1db80 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65  e used,.** there
1db90 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20   may be gaps in 
1dba0 74 68 65 20 6c 69 73 74 2e 0a 2a 2a 0a 2a 2a 20  the list..**.** 
1dbb0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1dbc0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
1dbd0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
1dbe0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1dbf0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
1dc00 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1dc10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1dc20 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
1dc30 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1dc40 2a 20 5b 48 31 33 36 30 31 5d 0a 2a 2f 0a 69 6e  * [H13601].*/.in
1dc50 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
1dc60 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
1dc70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
1dc80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1dc90 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
1dca0 61 72 61 6d 65 74 65 72 20 7b 48 31 33 36 32 30  arameter {H13620
1dcb0 7d 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S70300>.**.**
1dcc0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
1dcd0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1dce0 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  to the name of t
1dcf0 68 65 20 6e 2d 74 68 0a 2a 2a 20 5b 53 51 4c 20  he n-th.** [SQL 
1dd00 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 20  parameter] in a 
1dd10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1dd20 65 6e 74 5d 2e 0a 2a 2a 20 53 51 4c 20 70 61 72  ent]..** SQL par
1dd30 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
1dd40 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
1dd50 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
1dd60 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
1dd70 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
1dd80 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
1dd90 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
1dda0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
1ddb0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
1ddc0 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
1ddd0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
1dde0 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
1ddf0 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
1de00 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
1de10 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 0a 2a 2a   of the name..**
1de20 20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   Parameters of t
1de30 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
1de40 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
1de50 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
1de60 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
1de70 61 6c 73 6f 20 72 65 66 65 72 72 65 64 20 74 6f  also referred to
1de80 20 61 73 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   as "anonymous p
1de90 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
1dea0 2a 20 54 68 65 20 66 69 72 73 74 20 68 6f 73 74  * The first host
1deb0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
1dec0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
1ded0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  t 0..**.** If th
1dee0 65 20 76 61 6c 75 65 20 6e 20 69 73 20 6f 75 74  e value n is out
1def0 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
1df00 74 68 65 20 6e 2d 74 68 20 70 61 72 61 6d 65 74  the n-th paramet
1df10 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
1df20 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
1df30 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 72  returned.  The r
1df40 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
1df50 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
1df60 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
1df70 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
1df80 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
1df90 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
1dfa0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
1dfb0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
1dfc0 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
1dfd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1dfe0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
1dff0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1e000 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1e010 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
1e020 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1e030 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
1e040 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
1e050 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1e060 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _index()]..**.**
1e070 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
1e080 2a 20 5b 48 31 33 36 32 31 5d 0a 2a 2f 0a 63 6f  * [H13621].*/.co
1e090 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1e0a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1e0b0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
1e0c0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
1e0d0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
1e0e0 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
1e0f0 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
1e100 6d 65 20 7b 48 31 33 36 34 30 7d 20 3c 53 37 30  me {H13640} <S70
1e110 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72  300>.**.** Retur
1e120 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
1e130 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
1e140 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
1e150 20 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61   The.** index va
1e160 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
1e170 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
1e180 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
1e190 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
1e1a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1e1b0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1e1c0 5d 2e 20 20 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  ].  A zero.** is
1e1d0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
1e1e0 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
1e1f0 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 54 68  er is found.  Th
1e200 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
1e210 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
1e220 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
1e230 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
1e240 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
1e250 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
1e260 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
1e270 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e280 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1e290 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1e2a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1e2b0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1e2c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1e2d0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1e2e0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1e2f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1e300 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2a 0a  er_index()]..**.
1e310 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
1e320 0a 2a 2a 20 5b 48 31 33 36 34 31 5d 0a 2a 2f 0a  .** [H13641].*/.
1e330 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1e340 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1e350 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1e360 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
1e370 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
1e380 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
1e390 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
1e3a0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
1e3b0 7b 48 31 33 36 36 30 7d 20 3c 53 37 30 33 30 30  {H13660} <S70300
1e3c0 3e 0a 2a 2a 0a 2a 2a 20 43 6f 6e 74 72 61 72 79  >.**.** Contrary
1e3d0 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
1e3e0 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
1e3f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
1e400 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
1e410 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
1e420 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
1e430 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
1e440 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
1e450 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
1e460 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
1e470 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
1e480 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 52 65 71   NULL..**.** Req
1e490 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48  uirements:.** [H
1e4a0 31 33 36 36 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71  13661].*/.int sq
1e4b0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
1e4c0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
1e4d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
1e4e0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
1e4f0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
1e500 75 6c 74 20 53 65 74 20 7b 48 31 33 37 31 30 7d  ult Set {H13710}
1e510 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S10700>.**.** 
1e520 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
1e530 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1e540 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
1e550 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
1e560 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
1e570 65 6d 65 6e 74 5d 2e 20 54 68 69 73 20 72 6f 75  ement]. This rou
1e580 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
1e590 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
1e5a0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
1e5b0 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
1e5c0 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
1e5d0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
1e5e0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  ])..**.** Requir
1e5f0 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 37  ements:.** [H137
1e600 31 31 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  11].*/.int sqlit
1e610 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
1e620 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
1e630 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
1e640 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
1e650 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
1e660 53 65 74 20 7b 48 31 33 37 32 30 7d 20 3c 53 31  Set {H13720} <S1
1e670 30 37 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  0700>.**.** Thes
1e680 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1e690 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
1e6a0 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
1e6b0 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
1e6c0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
1e6d0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
1e6e0 61 74 65 6d 65 6e 74 2e 20 20 54 68 65 20 73 71  atement.  The sq
1e6f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1e700 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
1e710 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1e720 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
1e730 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1e740 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
1e750 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
1e760 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
1e770 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
1e780 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1e790 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 54 68  F-16 string.  Th
1e7a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1e7b0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
1e7c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
1e7d0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
1e7e0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
1e7f0 61 74 65 6d 65 6e 74 2e 20 54 68 65 20 73 65 63  atement. The sec
1e800 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
1e810 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
1e820 75 6d 62 65 72 2e 20 20 54 68 65 20 6c 65 66 74  umber.  The left
1e830 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
1e840 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 54  umber 0..**.** T
1e850 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
1e860 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
1e870 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
1e880 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1e890 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
1e8a0 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
1e8b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
1e8c0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  ] or until the n
1e8d0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
1e8e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1e8f0 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
1e900 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
1e910 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
1e920 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 73 71 6c  mn..**.** If sql
1e930 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
1e940 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
1e950 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
1e960 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
1e970 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
1e980 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
1e990 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
1e9a0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
1e9b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
1e9c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1e9d0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
1e9e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
1e9f0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
1ea00 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
1ea10 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
1ea20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
1ea30 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
1ea40 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
1ea50 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
1ea60 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
1ea70 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
1ea80 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
1ea90 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
1eaa0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
1eab0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a 2a  o the next..**.*
1eac0 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
1ead0 2a 2a 20 5b 48 31 33 37 32 31 5d 20 5b 48 31 33  ** [H13721] [H13
1eae0 37 32 33 5d 20 5b 48 31 33 37 32 34 5d 20 5b 48  723] [H13724] [H
1eaf0 31 33 37 32 35 5d 20 5b 48 31 33 37 32 36 5d 20  13725] [H13726] 
1eb00 5b 48 31 33 37 32 37 5d 0a 2a 2f 0a 63 6f 6e 73  [H13727].*/.cons
1eb10 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1eb20 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
1eb30 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
1eb40 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
1eb50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
1eb60 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
1eb70 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
1eb80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
1eb90 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
1eba0 20 51 75 65 72 79 20 52 65 73 75 6c 74 20 7b 48   Query Result {H
1ebb0 31 33 37 34 30 7d 20 3c 53 31 30 37 30 30 3e 0a  13740} <S10700>.
1ebc0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1ebd0 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
1ebe0 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
1ebf0 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e 20 6f 66  e what column of
1ec00 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c 65 20 69   what.** table i
1ec10 6e 20 77 68 69 63 68 20 64 61 74 61 62 61 73 65  n which database
1ec20 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 20 5b   a result of a [
1ec30 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1ec40 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e 0a 2a 2a  t comes from..**
1ec50 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   The name of the
1ec60 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
1ec70 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
1ec80 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
1ec90 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
1eca0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
1ecb0 6e 67 2e 20 20 54 68 65 20 5f 64 61 74 61 62 61  ng.  The _databa
1ecc0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
1ecd0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
1ece0 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
1ecf0 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
1ed00 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
1ed10 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
1ed20 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
1ed30 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
1ed40 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 54 68 65  umn name..** The
1ed50 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
1ed60 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
1ed70 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1ed80 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74  atement] is dest
1ed90 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b  royed.** using [
1eda0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1edb0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
1edc0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
1edd0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
1ede0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
1edf0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
1ee00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 73  .**.** The names
1ee10 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
1ee20 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
1ee30 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
1ee40 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
1ee50 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
1ee60 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  n..**.** The fir
1ee70 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1ee80 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 6c  he following cal
1ee90 6c 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  ls is a [prepare
1eea0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
1eeb0 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
1eec0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
1eed0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
1eee0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
1eef0 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
1ef00 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
1ef10 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
1ef20 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
1ef30 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 4e 74 68  **.** If the Nth
1ef40 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
1ef50 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
1ef60 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
1ef70 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
1ef80 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
1ef90 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
1efa0 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
1efb0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
1efc0 2a 2a 20 4e 55 4c 4c 2e 20 20 54 68 65 73 65 20  ** NULL.  These 
1efd0 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c  routine might al
1efe0 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69  so return NULL i
1eff0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
1f000 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f  ation error.** o
1f010 63 63 75 72 73 2e 20 20 4f 74 68 65 72 77 69 73  ccurs.  Otherwis
1f020 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
1f030 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
1f040 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1f050 2c 20 74 61 62 6c 65 0a 2a 2a 20 61 6e 64 20 63  , table.** and c
1f060 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
1f070 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
1f080 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
1f090 6d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 69 74 68  m..**.** As with
1f0a0 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
1f0b0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f  e APIs, those po
1f0c0 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36  stfixed with "16
1f0d0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
1f0e0 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
1f0f0 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75  gs, the other fu
1f100 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
1f110 54 46 2d 38 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  TF-8. {END}.**.*
1f120 2a 20 54 68 65 73 65 20 41 50 49 73 20 61 72 65  * These APIs are
1f130 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
1f140 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
1f150 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1f160 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1f170 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
1f180 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
1f190 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
1f1a0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 7b 41 31  fined..**.** {A1
1f1b0 33 37 35 31 7d 0a 2a 2a 20 49 66 20 74 77 6f 20  3751}.** If two 
1f1c0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
1f1d0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
1f1e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1f1f0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
1f200 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
1f210 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
1f220 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
1f230 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
1f240 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
1f250 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  defined..**.** R
1f260 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20  equirements:.** 
1f270 5b 48 31 33 37 34 31 5d 20 5b 48 31 33 37 34 32  [H13741] [H13742
1f280 5d 20 5b 48 31 33 37 34 33 5d 20 5b 48 31 33 37  ] [H13743] [H137
1f290 34 34 5d 20 5b 48 31 33 37 34 35 5d 20 5b 48 31  44] [H13745] [H1
1f2a0 33 37 34 36 5d 20 5b 48 31 33 37 34 38 5d 0a 2a  3746] [H13748].*
1f2b0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
1f2c0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
1f2d0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1f2e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1f2f0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
1f300 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
1f310 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
1f320 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
1f330 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f340 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
1f350 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
1f360 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
1f370 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
1f380 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
1f390 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1f3a0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
1f3b0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1f3c0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
1f3d0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
1f3e0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
1f3f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
1f400 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
1f410 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
1f420 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
1f430 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
1f440 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
1f450 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
1f460 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
1f470 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
1f480 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1f490 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
1f4a0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1f4b0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
1f4c0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
1f4d0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
1f4e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
1f4f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1f500 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
1f510 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
1f520 79 20 52 65 73 75 6c 74 20 7b 48 31 33 37 36 30  y Result {H13760
1f530 7d 20 3c 53 31 30 37 30 30 3e 0a 2a 2a 0a 2a 2a  } <S10700>.**.**
1f540 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
1f550 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
1f560 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1f570 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
1f580 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
1f590 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
1f5a0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1f5b0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
1f5c0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
1f5d0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
1f5e0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
1f5f0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
1f600 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
1f610 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
1f620 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
1f630 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
1f640 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  n is returned.  
1f650 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
1f660 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
1f670 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
1f680 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
1f690 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
1f6a0 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
1f6b0 72 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 72 65 74  rned..** The ret
1f6c0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
1f6d0 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
1f6e0 6f 64 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a  oded. {END}.**.*
1f6f0 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  * For example, g
1f700 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
1f710 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
1f720 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
1f730 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
1f740 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
1f750 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
1f760 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
1f770 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
1f780 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
1f790 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
1f7a0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
1f7b0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
1f7c0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
1f7d0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
1f7e0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
1f7f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1f800 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
1f810 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
1f820 30 29 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  0)..**.** SQLite
1f830 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
1f840 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
1f850 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
1f860 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
1f870 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
1f880 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
1f890 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
1f8a0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
1f8b0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
1f8c0 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
1f8d0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
1f8e0 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
1f8f0 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
1f900 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
1f910 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
1f920 74 61 74 69 63 2e 20 20 54 79 70 65 0a 2a 2a 20  tatic.  Type.** 
1f930 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
1f940 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
1f950 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
1f960 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
1f970 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
1f980 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2a 0a 2a  ose values..**.*
1f990 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
1f9a0 2a 2a 20 5b 48 31 33 37 36 31 5d 20 5b 48 31 33  ** [H13761] [H13
1f9b0 37 36 32 5d 20 5b 48 31 33 37 36 33 5d 0a 2a 2f  762] [H13763].*/
1f9c0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1f9d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
1f9e0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
1f9f0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
1fa00 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
1fa10 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
1fa20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
1fa30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1fa40 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
1fa50 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 7b 48  SQL Statement {H
1fa60 31 33 32 30 30 7d 20 3c 53 31 30 30 30 30 3e 0a  13200} <S10000>.
1fa70 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
1fa80 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fa90 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
1faa0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
1fab0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
1fac0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
1fad0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1fae0 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
1faf0 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
1fb00 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
1fb10 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1fb20 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
1fb30 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
1fb40 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
1fb50 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
1fb60 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
1fb70 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
1fb80 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
1fb90 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
1fba0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
1fbb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1fbc0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
1fbd0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
1fbe0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
1fbf0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
1fc00 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
1fc10 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
1fc20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1fc30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1fc40 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
1fc50 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
1fc60 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
1fc70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1fc80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1fc90 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
1fca0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
1fcb0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
1fcc0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
1fcd0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
1fce0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
1fcf0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
1fd00 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
1fd10 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
1fd20 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  d..**.** In the 
1fd30 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1fd40 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
1fd50 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
1fd60 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
1fd70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
1fd80 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
1fd90 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
1fda0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
1fdb0 53 45 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65  SE]..** With the
1fdc0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
1fdd0 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
1fde0 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
1fdf0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
1fe00 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
1fe10 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
1fe20 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
1fe30 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
1fe40 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
1fe50 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
1fe60 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
1fe70 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
1fe80 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
1fe90 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
1fea0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
1feb0 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
1fec0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
1fed0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
1fee0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
1fef0 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
1ff00 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
1ff10 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
1ff20 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
1ff30 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
1ff40 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a  ccurs within a.*
1ff50 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  * explicit trans
1ff60 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20  action then you 
1ff70 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20  should rollback 
1ff80 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
1ff90 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e  before.** contin
1ffa0 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  uing..**.** [SQL
1ffb0 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
1ffc0 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
1ffd0 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
1ffe0 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
1fff0 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
20000 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
20010 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
20020 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
20030 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
20040 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
20050 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
20060 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
20070 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
20080 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
20090 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
200a0 74 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  te..**.** If the
200b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
200c0 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
200d0 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
200e0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
200f0 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
20100 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
20110 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
20120 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
20130 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
20140 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
20150 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
20160 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
20170 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
20180 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
20190 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
201a0 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
201b0 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
201c0 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
201d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
201e0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
201f0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
20200 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
20210 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
20220 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
20230 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
20240 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
20250 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
20260 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
20270 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
20280 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
20290 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
202a0 29 5d 2e 0a 2a 2a 20 57 69 74 68 20 74 68 65 20  )]..** With the 
202b0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
202c0 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
202d0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
202e0 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
202f0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
20300 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
20310 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
20320 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
20330 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
20340 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
20350 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
20360 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
20370 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20380 5d 2e 20 20 49 6e 20 74 68 65 20 22 76 32 22 20  ].  In the "v2" 
20390 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
203a0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
203b0 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
203c0 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
203d0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
203e0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
203f0 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
20400 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
20410 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
20420 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
20430 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
20440 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
20450 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20460 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
20470 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
20480 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
20490 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
204a0 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
204b0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
204c0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
204d0 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
204e0 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
204f0 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
20500 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
20510 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20520 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
20530 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
20540 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
20550 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
20560 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 3c  in time..**.** <
20570 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
20580 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
20590 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
205a0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
205b0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
205c0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
205d0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
205e0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
205f0 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
20600 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
20610 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
20620 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
20630 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
20640 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
20650 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
20660 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
20670 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
20680 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
20690 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
206a0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
206b0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
206c0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
206d0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
206e0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
206f0 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
20700 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
20710 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
20720 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
20730 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
20740 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
20750 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
20760 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
20770 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20780 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
20790 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
207a0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
207b0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
207c0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
207d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
207e0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
207f0 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
20800 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
20810 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
20820 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
20830 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
20840 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
20850 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
20860 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
20870 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
20880 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 32 30 32  ents:.** [H13202
20890 5d 20 5b 48 31 35 33 30 34 5d 20 5b 48 31 35 33  ] [H15304] [H153
208a0 30 36 5d 20 5b 48 31 35 33 30 38 5d 20 5b 48 31  06] [H15308] [H1
208b0 35 33 31 30 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  5310].*/.int sql
208c0 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
208d0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
208e0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
208f0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
20900 61 20 72 65 73 75 6c 74 20 73 65 74 20 7b 48 31  a result set {H1
20910 33 37 37 30 7d 20 3c 53 31 30 37 30 30 3e 0a 2a  3770} <S10700>.*
20920 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20 74 68 65  *.** Returns the
20930 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75 65   number of value
20940 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  s in the current
20950 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
20960 6c 74 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 52 65  lt set..**.** Re
20970 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
20980 48 31 33 37 37 31 5d 20 5b 48 31 33 37 37 32 5d  H13771] [H13772]
20990 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
209a0 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
209b0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
209c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
209d0 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
209e0 74 61 74 79 70 65 73 20 7b 48 31 30 32 36 35 7d  tatypes {H10265}
209f0 20 3c 53 31 30 31 31 30 3e 3c 53 31 30 31 32 30   <S10110><S10120
20a00 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  >.** KEYWORDS: S
20a10 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
20a20 20 7b 48 31 30 32 36 36 7d 20 45 76 65 72 79 20   {H10266} Every 
20a30 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
20a40 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
20a50 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
20a60 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
20a70 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
20a80 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
20a90 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
20aa0 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
20ab0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
20ac0 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
20ad0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
20ae0 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44  LL.** </ul> {END
20af0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
20b00 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
20b10 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
20b20 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
20b30 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
20b40 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
20b50 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
20b60 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
20b70 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
20b80 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
20b90 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
20ba0 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
20bb0 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
20bc0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
20bd0 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
20be0 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
20bf0 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
20c00 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
20c10 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
20c20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
20c30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
20c40 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
20c50 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
20c60 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
20c70 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
20c80 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
20c90 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
20ca0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
20cb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
20cc0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
20cd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
20ce0 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
20cf0 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
20d00 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
20d10 51 75 65 72 79 20 7b 48 31 33 38 30 30 7d 20 3c  Query {H13800} <
20d20 53 31 30 37 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S10700>.** KEYWO
20d30 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
20d40 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
20d50 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
20d60 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
20d70 73 75 6c 74 20 73 65 74 20 71 75 65 72 79 22 20  sult set query" 
20d80 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
20d90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
20da0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
20db0 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
20dc0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
20dd0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
20de0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
20df0 2e 20 20 49 6e 20 65 76 65 72 79 20 63 61 73 65  .  In every case
20e00 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
20e10 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
20e20 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
20e30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20e40 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
20e50 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
20e60 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
20e70 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
20e80 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
20e90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
20ea0 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
20eb0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
20ec0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
20ed0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
20ee0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
20ef0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
20f00 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
20f10 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 6c 65  eturned.  The le
20f20 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
20f30 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
20f40 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
20f50 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
20f60 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
20f70 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
20f80 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
20f90 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
20fa0 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
20fb0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
20fc0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
20fd0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
20fe0 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
20ff0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
21000 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
21010 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
21020 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
21030 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
21040 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
21050 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
21060 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
21070 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
21080 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
21090 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
210a0 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
210b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
210c0 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
210d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
210e0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
210f0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
21100 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
21110 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
21120 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
21130 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
21140 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
21150 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
21160 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
21170 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
21180 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21190 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
211a0 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
211b0 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
211c0 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
211d0 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
211e0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
211f0 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
21200 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
21210 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
21220 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
21230 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
21240 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
21250 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
21260 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
21270 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
21280 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
21290 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
212a0 75 6d 6e 2e 20 20 54 68 65 20 72 65 74 75 72 6e  umn.  The return
212b0 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
212c0 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
212d0 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
212e0 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
212f0 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
21300 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
21310 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
21320 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
21330 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
21340 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
21350 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
21360 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
21370 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
21380 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
21390 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
213a0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
213b0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
213c0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
213d0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
213e0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
213f0 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
21400 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
21410 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
21420 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
21430 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
21440 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
21450 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
21460 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c 74  ** If the result
21470 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
21480 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
21490 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
214a0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
214b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
214c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
214d0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
214e0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 49 66 20  r string..** If 
214f0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
21500 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
21510 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
21520 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
21530 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
21540 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
21550 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
21560 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
21570 0a 2a 2a 20 49 66 20 74 68 65 20 72 65 73 75 6c  .** If the resul
21580 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
21590 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
215a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
215b0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
215c0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
215d0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
215e0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
215f0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
21600 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
21610 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
21620 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 54 68 65 20   string..** The 
21630 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64  value returned d
21640 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
21650 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
21660 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  tor at the end.*
21670 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
21680 20 20 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74    For clarity: t
21690 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
216a0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
216b0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
216c0 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
216d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
216e0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 53  racters..**.** S
216f0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
21700 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
21710 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
21720 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
21730 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
21740 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
21750 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72   always zero ter
21760 6d 69 6e 61 74 65 64 2e 20 20 54 68 65 20 72 65  minated.  The re
21770 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
21780 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
21790 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
217a0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
217b0 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a  is an arbitrary.
217c0 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73  ** pointer, poss
217d0 69 62 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c  ibly even a NULL
217e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
217f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
21800 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75  mn_bytes16() rou
21810 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
21820 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
21830 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74  n_bytes().** but
21840 20 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75   leaves the resu
21850 6c 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20  lt in UTF-16 in 
21860 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
21870 72 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46  r instead of UTF
21880 2d 38 2e 0a 2a 2a 20 54 68 65 20 7a 65 72 6f 20  -8..** The zero 
21890 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f  terminator is no
218a0 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  t included in th
218b0 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20  is count..**.** 
218c0 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
218d0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
218e0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
218f0 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
21900 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
21910 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
21920 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
21930 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
21940 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
21950 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
21960 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
21970 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
21980 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
21990 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
219a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
219b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
219c0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
219d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
219e0 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
219f0 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
21a00 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
21a10 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
21a20 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
21a30 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
21a40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
21a50 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
21a60 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
21a70 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
21a80 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
21a90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
21aa0 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
21ab0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
21ac0 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
21ad0 69 61 74 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  iate.  For.** ex
21ae0 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
21af0 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
21b00 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
21b10 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
21b20 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
21b30 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
21b40 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
21b50 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
21b60 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
21b70 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
21b80 61 6c 6c 79 2e 20 20 54 68 65 20 66 6f 6c 6c 6f  ally.  The follo
21b90 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
21ba0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
21bb0 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
21bc0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
21bd0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
21be0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
21bf0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
21c00 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
21c10 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
21c20 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
21c30 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
21c40 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
21c50 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
21c60 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
21c70 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
21c80 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
21c90 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
21ca0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
21cb0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
21cc0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
21cd0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
21ce0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
21cf0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
21d00 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
21d10 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
21d20 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
21d30 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
21d40 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
21d50 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
21d60 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
21d70 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
21d80 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
21d90 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
21da0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
21db0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
21dc0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
21dd0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
21de0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
21df0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
21e00 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
21e10 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
21e20 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
21e30 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
21e40 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
21e50 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
21e60 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
21e70 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
21e80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
21e90 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
21ea0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
21eb0 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
21ec0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
21ed0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
21ee0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
21ef0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
21f00 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
21f10 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
21f20 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
21f30 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
21f40 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
21f50 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
21f60 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
21f70 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
21f80 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
21f90 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
21fa0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
21fb0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
21fc0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
21fd0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
21fe0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
21ff0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
22000 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
22010 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
22020 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
22030 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
22040 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  * </blockquote>.
22050 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
22060 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65  above makes refe
22070 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72  rence to standar
22080 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63  d C library func
22090 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20  tions atoi().** 
220a0 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c  and atof().  SQL
220b0 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61  ite does not rea
220c0 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75  lly use these fu
220d0 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73  nctions.  It has
220e0 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69   its.** own equi
220f0 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20  valent internal 
22100 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61  routines.  The a
22110 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29  toi() and atof()
22120 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73   names are.** us
22130 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20  ed in the table 
22140 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20  for brevity and 
22150 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65  because they are
22160 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73   familiar to mos
22170 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65  t.** C programme
22180 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  rs..**.** Note t
22190 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f  hat when type co
221a0 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c  nversions occur,
221b0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
221c0 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63  ed by prior.** c
221d0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
221e0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73  column_blob(), s
221f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
22200 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  xt(), and/or.** 
22210 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22220 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69  ext16() may be i
22230 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54  nvalidated..** T
22240 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
22250 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61  and pointer inva
22260 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lidations might 
22270 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
22280 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a  following cases:
22290 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
222a0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
222b0 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f  content is a BLO
222c0 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  B and sqlite3_co
222d0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a  lumn_text() or.*
222e0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
222f0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
22300 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72  s called.  A zer
22310 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67  o-terminator mig
22320 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20  ht.**      need 
22330 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74  to be added to t
22340 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a  he string.</li>.
22350 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
22360 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
22370 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71  TF-8 text and sq
22380 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
22390 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20  es16() or.**    
223a0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
223b0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
223c0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
223d0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
223e0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
223f0 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  TF-16.</li>.** <
22400 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
22410 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31  content is UTF-1
22420 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74  6 text and sqlit
22430 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
22440 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
22450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
22460 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
22470 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
22480 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
22490 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f       to UTF-8.</
224a0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
224b0 2a 2a 20 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  ** Conversions b
224c0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
224d0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
224e0 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
224f0 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
22500 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
22510 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
22520 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
22530 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
22540 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
22550 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
22560 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20 77  nter points to w
22570 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
22580 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
22590 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
225a0 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
225b0 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
225c0 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
225d0 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
225e0 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
225f0 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
22600 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
22610 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
22620 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
22630 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
22640 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
22650 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
22660 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
22670 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
22680 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
22690 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
226a0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
226b0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
226c0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
226d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
226e0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
226f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
22700 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
22710 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
22720 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
22730 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
22740 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
22750 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
22760 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
22770 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
22780 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
22790 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
227a0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
227b0 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
227c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
227d0 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
227e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
227f0 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
22800 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
22810 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
22820 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
22830 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
22840 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
22850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
22860 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
22870 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
22880 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
22890 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
228a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
228b0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
228c0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
228d0 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
228e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
228f0 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
22900 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
22910 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
22920 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
22930 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
22940 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
22950 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  )..**.** The poi
22960 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
22970 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
22980 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
22990 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
229a0 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
229b0 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
229c0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
229d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
229e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
229f0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
22a00 65 64 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  ed.  The memory 
22a10 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
22a20 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
22a30 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
22a40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
22a50 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
22a60 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
22a70 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
22a80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
22a90 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
22aa0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
22ab0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
22ac0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
22ad0 0a 2a 2a 20 49 66 20 61 20 6d 65 6d 6f 72 79 20  .** If a memory 
22ae0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
22af0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
22b00 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
22b10 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
22b20 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
22b30 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
22b40 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
22b50 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
22b60 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
22b70 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
22b80 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
22b90 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
22ba0 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
22bb0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
22bc0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
22bd0 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
22be0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
22bf0 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72  M]..**.** Requir
22c00 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 33 38  ements:.** [H138
22c10 30 33 5d 20 5b 48 31 33 38 30 36 5d 20 5b 48 31  03] [H13806] [H1
22c20 33 38 30 39 5d 20 5b 48 31 33 38 31 32 5d 20 5b  3809] [H13812] [
22c30 48 31 33 38 31 35 5d 20 5b 48 31 33 38 31 38 5d  H13815] [H13818]
22c40 20 5b 48 31 33 38 32 31 5d 20 5b 48 31 33 38 32   [H13821] [H1382
22c50 34 5d 0a 2a 2a 20 5b 48 31 33 38 32 37 5d 20 5b  4].** [H13827] [
22c60 48 31 33 38 33 30 5d 0a 2a 2f 0a 63 6f 6e 73 74  H13830].*/.const
22c70 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
22c80 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
22c90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
22ca0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
22cb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
22cc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
22cd0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
22ce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
22cf0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
22d00 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
22d10 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
22d20 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
22d30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
22d40 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
22d50 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
22d60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
22d70 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
22d80 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
22d90 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
22da0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
22db0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
22dc0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
22dd0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
22de0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
22df0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
22e00 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
22e10 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
22e20 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
22e30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
22e40 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
22e50 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
22e60 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
22e70 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
22e80 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
22e90 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
22ea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22eb0 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
22ec0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
22ed0 62 6a 65 63 74 20 7b 48 31 33 33 30 30 7d 20 3c  bject {H13300} <
22ee0 53 37 30 33 30 30 3e 3c 53 33 30 31 30 30 3e 0a  S70300><S30100>.
22ef0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
22f00 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
22f10 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
22f20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
22f30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
22f40 2e 0a 2a 2a 20 49 66 20 74 68 65 20 73 74 61 74  ..** If the stat
22f50 65 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74  ement was execut
22f60 65 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ed successfully 
22f70 6f 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20  or not executed 
22f80 61 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20  at all, then.** 
22f90 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74  SQLITE_OK is ret
22fa0 75 72 6e 65 64 2e 20 49 66 20 65 78 65 63 75 74  urned. If execut
22fb0 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
22fc0 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e  ment failed then
22fd0 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
22fe0 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
22ff0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
23000 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
23010 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
23020 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
23030 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20 74  y point during t
23040 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
23050 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
23060 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 49 66   statement].  If
23070 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d 61 63   the virtual mac
23080 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hine has not.** 
23090 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
230a0 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20 72 6f  ion when this ro
230b0 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c  utine is called,
230c0 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a   that is like.**
230d0 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e   encountering an
230e0 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71   error or an [sq
230f0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 20  lite3_interrupt 
23100 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a  | interrupt]..**
23110 20 49 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61   Incomplete upda
23120 74 65 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65  tes may be rolle
23130 64 20 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73  d back and trans
23140 61 63 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64  actions canceled
23150 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f  ,.** depending o
23160 6e 20 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e  n the circumstan
23170 63 65 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ces, and the.** 
23180 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74  [error code] ret
23190 75 72 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53  urned will be [S
231a0 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
231b0 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73  .** Requirements
231c0 3a 0a 2a 2a 20 5b 48 31 31 33 30 32 5d 20 5b 48  :.** [H11302] [H
231d0 31 31 33 30 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71  11304].*/.int sq
231e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
231f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
23200 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
23210 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
23220 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
23230 20 4f 62 6a 65 63 74 20 7b 48 31 33 33 33 30 7d   Object {H13330}
23240 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S70300>.**.** 
23250 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
23260 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
23270 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
23280 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
23290 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
232a0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
232b0 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
232c0 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
232d0 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 53 51 4c 20  ted..** Any SQL 
232e0 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
232f0 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
23300 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
23310 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
23320 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
23330 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
23340 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
23350 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
23360 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
23370 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
23380 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
23390 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ndings..**.** {H
233a0 31 31 33 33 32 7d 20 54 68 65 20 5b 73 71 6c 69  11332} The [sqli
233b0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
233c0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
233d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
233e0 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 20 20 20  tement] S.**    
233f0 20 20 20 20 20 20 62 61 63 6b 20 74 6f 20 74 68        back to th
23400 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
23410 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
23420 2a 20 7b 48 31 31 33 33 34 7d 20 49 66 20 74 68  * {H11334} If th
23430 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
23440 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
23450 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
23460 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65  **          [pre
23470 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23480 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
23490 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
234a0 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 20 20  ITE_DONE],.**   
234b0 20 20 20 20 20 20 20 6f 72 20 69 66 20 5b 73 71         or if [sq
234c0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
234d0 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
234e0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
234f0 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ,.**          th
23500 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
23510 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
23520 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
23530 20 7b 48 31 31 33 33 36 7d 20 49 66 20 74 68 65   {H11336} If the
23540 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
23550 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
23560 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
23570 2a 20 20 20 20 20 20 20 20 20 20 5b 70 72 65 70  *          [prep
23580 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
23590 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
235a0 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 20 20  rror, then.**   
235b0 20 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f         [sqlite3_
235c0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
235d0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
235e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
235f0 2a 0a 2a 2a 20 7b 48 31 31 33 33 38 7d 20 54 68  *.** {H11338} Th
23600 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
23610 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
23620 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
23630 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 20 20 20  he values.**    
23640 20 20 20 20 20 20 6f 66 20 61 6e 79 20 5b 73 71        of any [sq
23650 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
23660 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
23670 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23680 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
23690 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
236a0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
236b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
236c0 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
236d0 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
236e0 74 69 6f 6e 73 20 7b 48 31 36 31 30 30 7d 20 3c  tions {H16100} <
236f0 53 32 30 32 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f  S20200>.** KEYWO
23700 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
23710 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
23720 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
23730 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
23740 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
23750 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
23760 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
23770 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
23780 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 74  s}.**.** These t
23790 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  wo functions (co
237a0 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
237b0 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
237c0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
237d0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
237e0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
237f0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
23800 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
23810 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
23820 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
23830 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
23840 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
23850 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65  ly difference be
23860 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f  tween the.** two
23870 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63   is that the sec
23880 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ond parameter, t
23890 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  he name of the (
238a0 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
238b0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
238c0 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20  , is encoded in 
238d0 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65  UTF-8 for sqlite
238e0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
238f0 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a  n() and UTF-16.*
23900 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
23910 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
23920 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  )..**.** The fir
23930 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
23940 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
23950 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
23960 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
23970 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
23980 61 64 64 65 64 2e 20 20 49 66 20 61 20 73 69 6e  added.  If a sin
23990 67 6c 65 20 70 72 6f 67 72 61 6d 20 75 73 65 73  gle program uses
239a0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
239b0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
239c0 63 74 69 6f 6e 20 69 6e 74 65 72 6e 61 6c 6c 79  ction internally
239d0 2c 20 74 68 65 6e 20 53 51 4c 20 66 75 6e 63 74  , then SQL funct
239e0 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
239f0 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 20  ed individually 
23a00 74 6f 0a 2a 2a 20 65 61 63 68 20 64 61 74 61 62  to.** each datab
23a10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a  ase connection..
23a20 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
23a30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
23a40 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
23a50 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
23a60 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
23a70 65 64 65 66 69 6e 65 64 2e 20 20 54 68 65 20 6c  edefined.  The l
23a80 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
23a90 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
23aa0 32 35 35 20 62 79 74 65 73 2c 20 65 78 63 6c 75  255 bytes, exclu
23ab0 73 69 76 65 20 6f 66 0a 2a 2a 20 74 68 65 20 7a  sive of.** the z
23ac0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
23ad0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e   Note that the n
23ae0 61 6d 65 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  ame length limit
23af0 20 69 73 20 69 6e 20 62 79 74 65 73 2c 20 6e 6f   is in bytes, no
23b00 74 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 2e  t.** characters.
23b10 20 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f    Any attempt to
23b20 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
23b30 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
23b40 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
23b50 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
23b60 45 52 52 4f 52 5d 20 62 65 69 6e 67 20 72 65 74  ERROR] being ret
23b70 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
23b80 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
23b90 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68   (nArg).** is th
23ba0 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
23bb0 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
23bc0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
23bd0 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
23be0 73 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 6d  s. If this param
23bf0 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
23c00 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
23c10 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
23c20 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
23c30 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
23c40 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
23c50 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
23c60 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
23c70 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
23c80 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
23c90 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
23ca0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
23cb0 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
23cc0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
23cd0 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
23ce0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
23cf0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ned..**.** The f
23d00 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
23d10 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
23d20 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
23d30 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
23d40 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
23d50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
23d60 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
23d70 70 61 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79  parameters.  Any
23d80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
23d90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
23da0 75 6c 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77  uld be able to w
23db0 6f 72 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68  ork.** work with
23dc0 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
23dd0 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
23de0 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
23df0 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
23e00 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
23e10 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
23e20 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
23e30 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
23e40 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
23e50 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
23e60 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
23e70 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
23e80 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
23e90 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
23ea0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
23eb0 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
23ec0 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
23ed0 54 65 78 74 52 65 70 2e 0a 2a 2a 20 57 68 65 6e  TextRep..** When
23ee0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
23ef0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
23f00 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
23f10 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
23f20 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
23f30 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
23f40 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
23f50 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
23f60 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
23f70 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
23f80 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
23f90 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
23fa0 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
23fb0 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
23fc0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
23fd0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
23fe0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
23ff0 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
24000 2a 2a 20 54 68 65 20 66 69 66 74 68 20 70 61 72  ** The fifth par
24010 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
24020 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
24030 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
24040 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
24050 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
24060 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
24070 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
24080 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
24090 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  )]..**.** The se
240a0 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
240b0 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
240c0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
240d0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
240e0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
240f0 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
24100 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
24110 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
24120 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
24130 67 61 74 65 2e 20 41 20 73 63 61 6c 61 72 20 53  gate. A scalar S
24140 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
24150 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
24160 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
24170 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
24180 6f 6e 6c 79 2c 20 4e 55 4c 4c 20 70 6f 69 6e 74  only, NULL point
24190 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ers should be pa
241a0 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
241b0 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
241c0 70 61 72 61 6d 65 74 65 72 73 2e 20 41 6e 20 61  parameters. An a
241d0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
241e0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
241f0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
24200 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
24210 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
24220 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73 65   should be passe
24230 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 54 6f 20  d for xFunc. To 
24240 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69  delete an existi
24250 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  ng.** SQL functi
24260 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c  on or aggregate,
24270 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72 20 61   pass NULL for a
24280 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
24290 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a  n callbacks..**.
242a0 2a 2a 20 49 74 20 69 73 20 70 65 72 6d 69 74 74  ** It is permitt
242b0 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
242c0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
242d0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
242e0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
242f0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
24300 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
24310 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
24320 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
24330 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
24340 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
24350 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 53 51  t encodings.  SQ
24360 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
24370 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
24380 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
24390 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
243a0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
243b0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
243c0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 41 20 66  on is used.  A f
243d0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
243e0 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f  tation with a no
243f0 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41  n-negative.** nA
24400 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rg parameter is 
24410 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74  a better match t
24420 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69  han a function i
24430 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
24440 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65  th.** a negative
24450 20 6e 41 72 67 2e 20 20 41 20 66 75 6e 63 74 69   nArg.  A functi
24460 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
24470 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
24480 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
24490 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
244a0 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
244b0 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
244c0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
244d0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
244e0 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
244f0 20 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72   A function wher
24500 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
24510 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
24520 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
24530 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
24540 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
24550 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
24560 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
24570 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
24580 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
24590 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
245a0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
245b0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
245c0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
245d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
245e0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  functions..** Th
245f0 65 20 66 69 72 73 74 20 61 70 70 6c 69 63 61 74  e first applicat
24600 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
24610 74 69 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65  tion with a give
24620 6e 20 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73  n name overrides
24630 20 61 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e   all.** built-in
24640 20 66 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68   functions in th
24650 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
24660 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74   connection] wit
24670 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  h the same name.
24680 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
24690 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
246a0 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20  ed functions of 
246b0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e  the same name on
246c0 6c 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20  ly override .** 
246d0 70 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f  prior applicatio
246e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
246f0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20  ons that are an 
24700 65 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20  exact match for 
24710 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
24720 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
24730 70 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69  preferred encodi
24740 6e 67 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 70 70  ng..**.** An app
24750 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
24760 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72   function is per
24770 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f  mitted to call o
24780 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
24790 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
247a0 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20  ver, such calls 
247b0 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73  must not.** clos
247c0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
247d0 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69  onnection nor fi
247e0 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20  nalize or reset 
247f0 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
24800 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69  statement in whi
24810 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ch the function 
24820 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a  is running..**.*
24830 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
24840 2a 2a 20 5b 48 31 36 31 30 33 5d 20 5b 48 31 36  ** [H16103] [H16
24850 31 30 36 5d 20 5b 48 31 36 31 30 39 5d 20 5b 48  106] [H16109] [H
24860 31 36 31 31 32 5d 20 5b 48 31 36 31 31 38 5d 20  16112] [H16118] 
24870 5b 48 31 36 31 32 31 5d 20 5b 48 31 36 31 32 37  [H16121] [H16127
24880 5d 0a 2a 2a 20 5b 48 31 36 31 33 30 5d 20 5b 48  ].** [H16130] [H
24890 31 36 31 33 33 5d 20 5b 48 31 36 31 33 36 5d 20  16133] [H16136] 
248a0 5b 48 31 36 31 33 39 5d 20 5b 48 31 36 31 34 32  [H16139] [H16142
248b0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
248c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
248d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
248e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
248f0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
24900 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
24910 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
24920 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
24930 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
24940 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
24950 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
24960 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
24970 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
24980 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
24990 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
249a0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
249b0 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
249c0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
249d0 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
249e0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
249f0 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
24a00 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
24a10 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
24a20 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
24a30 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
24a40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
24a50 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
24a60 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
24a70 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
24a80 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
24a90 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
24aa0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
24ab0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
24ac0 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
24ad0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
24ae0 69 6e 67 73 20 7b 48 31 30 32 36 37 7d 20 3c 53  ings {H10267} <S
24af0 35 30 32 30 30 3e 20 3c 48 31 36 31 30 30 3e 0a  50200> <H16100>.
24b00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
24b10 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
24b20 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
24b30 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
24b40 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
24b50 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
24b60 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
24b70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
24b80 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
24b90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
24ba0 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
24bb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
24bc0 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
24bd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
24be0 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
24bf0 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
24c00 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
24c10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
24c20 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
24c30 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
24c40 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
24c50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24c60 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
24c70 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
24c80 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
24c90 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
24ca0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
24cb0 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
24cc0 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
24cd0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
24ce0 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
24cf0 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
24d00 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
24d10 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
24d20 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
24d30 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
24d40 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
24d50 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
24d60 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
24d70 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
24d80 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
24d90 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
24da0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
24db0 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
24dc0 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
24dd0 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
24de0 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
24df0 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
24e00 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
24e10 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
24e20 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
24e30 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
24e40 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
24e50 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
24e60 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
24e70 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
24e80 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
24e90 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
24ea0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
24eb0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
24ec0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
24ed0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
24ee0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
24ef0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
24f00 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
24f10 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
24f20 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
24f30 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
24f40 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
24f50 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
24f60 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
24f70 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
24f80 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
24f90 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
24fa0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
24fb0 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
24fc0 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
24fd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24fe0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
24ff0 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
25000 72 20 56 61 6c 75 65 73 20 7b 48 31 35 31 30 30  r Values {H15100
25010 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20200>.**.**
25020 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
25030 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
25040 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
25050 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
25060 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
25070 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
25080 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
25090 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
250a0 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
250b0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
250c0 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
250d0 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
250e0 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
250f0 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
25100 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
25110 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
25120 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25130 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
25140 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25150 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
25160 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
25170 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
25180 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
25190 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
251a0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
251b0 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
251c0 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
251d0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
251e0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
251f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
25200 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
25210 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
25220 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
25230 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
25240 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
25250 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
25260 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
25270 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
25280 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
25290 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
252a0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
252b0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
252c0 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
252d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
252e0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
252f0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
25300 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
25310 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
25320 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
25330 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
25340 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
25350 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
25360 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
25370 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
25380 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
25390 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
253a0 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
253b0 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
253c0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
253d0 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
253e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
253f0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
25400 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
25410 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
25420 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
25430 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
25440 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  umber..**.** The
25450 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
25460 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
25470 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
25480 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
25490 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
254a0 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
254b0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 54 68 65  st machine.  The
254c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
254d0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
254e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
254f0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
25500 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
25510 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
25520 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
25530 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
25540 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
25550 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
25560 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
25570 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
25580 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
25590 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
255a0 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
255b0 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
255c0 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
255d0 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
255e0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
255f0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
25600 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
25610 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
25620 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
25630 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
25640 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
25650 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
25660 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
25670 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
25680 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
25690 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
256a0 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
256b0 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
256c0 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
256d0 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
256e0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
256f0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
25700 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
25710 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
25720 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
25730 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
25740 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
25750 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
25760 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
25770 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
25780 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
25790 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
257a0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
257b0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
257c0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
257d0 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
257e0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
257f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
25800 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
25810 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
25820 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
25830 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
25840 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
25850 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
25860 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
25870 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
25880 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
25890 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
258a0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
258b0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
258c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
258d0 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  rameters..**.** 
258e0 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
258f0 20 5b 48 31 35 31 30 33 5d 20 5b 48 31 35 31 30   [H15103] [H1510
25900 36 5d 20 5b 48 31 35 31 30 39 5d 20 5b 48 31 35  6] [H15109] [H15
25910 31 31 32 5d 20 5b 48 31 35 31 31 35 5d 20 5b 48  112] [H15115] [H
25920 31 35 31 31 38 5d 20 5b 48 31 35 31 32 31 5d 20  15118] [H15121] 
25930 5b 48 31 35 31 32 34 5d 0a 2a 2a 20 5b 48 31 35  [H15124].** [H15
25940 31 32 37 5d 20 5b 48 31 35 31 33 30 5d 20 5b 48  127] [H15130] [H
25950 31 35 31 33 33 5d 20 5b 48 31 35 31 33 36 5d 0a  15133] [H15136].
25960 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
25970 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
25980 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
25990 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
259a0 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
259b0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
259c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
259d0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
259e0 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
259f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
25a00 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
25a10 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
25a20 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
25a30 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
25a40 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
25a50 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
25a60 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
25a70 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
25a80 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
25a90 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
25aa0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
25ab0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
25ac0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
25ad0 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
25ae0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
25af0 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
25b00 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
25b10 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
25b20 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
25b30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
25b40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
25b50 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
25b60 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
25b70 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
25b80 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
25b90 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
25ba0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
25bb0 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
25bc0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 7b 48 31 36  ion Context {H16
25bd0 32 31 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a 2a  210} <S20200>.**
25be0 0a 2a 2a 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  .** The implemen
25bf0 74 61 74 69 6f 6e 20 6f 66 20 61 67 67 72 65 67  tation of aggreg
25c00 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
25c10 73 20 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  s use this routi
25c20 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 0a 2a  ne to allocate.*
25c30 2a 20 61 20 73 74 72 75 63 74 75 72 65 20 66 6f  * a structure fo
25c40 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
25c50 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  state..**.** The
25c60 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
25c70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
25c80 65 5f 63 6f 6e 74 65 78 74 28 29 20 72 6f 75 74  e_context() rout
25c90 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ine is called fo
25ca0 72 20 61 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61  r a.** particula
25cb0 72 20 61 67 67 72 65 67 61 74 65 2c 20 53 51 4c  r aggregate, SQL
25cc0 69 74 65 20 61 6c 6c 6f 63 61 74 65 73 20 6e 42  ite allocates nB
25cd0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  ytes of memory, 
25ce0 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 0a  zeroes out that.
25cf0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72  ** memory, and r
25d00 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
25d10 20 74 6f 20 69 74 2e 20 4f 6e 20 73 65 63 6f 6e   to it. On secon
25d20 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
25d30 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
25d40 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
25d50 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65  ontext() for the
25d60 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
25d70 66 75 6e 63 74 69 6f 6e 20 69 6e 64 65 78 2c 0a  function index,.
25d80 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
25d90 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
25da0 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
25db0 6f 6e 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  on of the aggreg
25dc0 61 74 65 20 63 61 6e 20 75 73 65 0a 2a 2a 20 74  ate can use.** t
25dd0 68 65 20 72 65 74 75 72 6e 65 64 20 62 75 66 66  he returned buff
25de0 65 72 20 74 6f 20 61 63 63 75 6d 75 6c 61 74 65  er to accumulate
25df0 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   data..**.** SQL
25e00 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
25e10 79 20 66 72 65 65 73 20 74 68 65 20 61 6c 6c 6f  y frees the allo
25e20 63 61 74 65 64 20 62 75 66 66 65 72 20 77 68 65  cated buffer whe
25e30 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  n the aggregate.
25e40 2a 2a 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  ** query conclud
25e50 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
25e60 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73 68  rst parameter sh
25e70 6f 75 6c 64 20 62 65 20 61 20 63 6f 70 79 20 6f  ould be a copy o
25e80 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
25e90 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
25ea0 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
25eb0 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
25ec0 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
25ed0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
25ee0 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
25ef0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
25f00 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2e  regate function.
25f10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
25f20 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
25f30 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
25f40 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
25f50 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
25f60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
25f70 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
25f80 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
25f90 2a 20 5b 48 31 36 32 31 31 5d 20 5b 48 31 36 32  * [H16211] [H162
25fa0 31 33 5d 20 5b 48 31 36 32 31 35 5d 20 5b 48 31  13] [H16215] [H1
25fb0 36 32 31 37 5d 0a 2a 2f 0a 76 6f 69 64 20 2a 73  6217].*/.void *s
25fc0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
25fd0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
25fe0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
25ff0 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
26000 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
26010 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
26020 20 7b 48 31 36 32 34 30 7d 20 3c 53 32 30 32 30   {H16240} <S2020
26030 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
26040 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
26050 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
26060 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
26070 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
26080 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
26090 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
260a0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
260b0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
260c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
260d0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
260e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
260f0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
26100 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
26110 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
26120 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
26130 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
26140 69 6f 6e 2e 20 7b 45 4e 44 7d 0a 2a 2a 0a 2a 2a  ion. {END}.**.**
26150 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
26160 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
26170 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
26180 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
26190 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
261a0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
261b0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  s running..**.**
261c0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
261d0 2a 20 5b 48 31 36 32 34 33 5d 0a 2a 2f 0a 76 6f  * [H16243].*/.vo
261e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
261f0 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
26200 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
26210 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
26220 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
26230 72 20 46 75 6e 63 74 69 6f 6e 73 20 7b 48 31 36  r Functions {H16
26240 32 35 30 7d 20 3c 53 36 30 36 30 30 3e 3c 53 32  250} <S60600><S2
26250 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0200>.**.** The 
26260 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
26270 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
26280 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
26290 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
262a0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
262b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
262c0 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
262d0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
262e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
262f0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
26300 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
26310 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
26320 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
26330 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
26340 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
26350 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
26360 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
26370 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
26380 2a 2a 20 5b 48 31 36 32 35 33 5d 0a 2a 2f 0a 73  ** [H16253].*/.s
26390 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
263a0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
263b0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
263c0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
263d0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
263e0 75 78 69 6c 69 61 72 79 20 44 61 74 61 20 7b 48  uxiliary Data {H
263f0 31 36 32 37 30 7d 20 3c 53 32 30 32 30 30 3e 0a  16270} <S20200>.
26400 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77  **.** The follow
26410 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e  ing two function
26420 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
26430 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
26440 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
26450 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
26460 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
26470 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
26480 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
26490 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
264a0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
264b0 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
264c0 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
264d0 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
264e0 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
264f0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
26500 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
26510 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
26520 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62  d. This may.** b
26530 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d  e used, for exam
26540 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65  ple, to add a re
26550 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e  gular-expression
26560 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72   matching scalar
26570 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68  .** function. Th
26580 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69  e compiled versi
26590 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61  on of the regula
265a0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20  r expression is 
265b0 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
265c0 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
265d0 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61   with the SQL va
265e0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
265f0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
26600 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e  sion.** pattern.
26610 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72    The compiled r
26620 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
26630 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
26640 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
26650 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
26660 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
26670 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67  so that the orig
26680 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72  inal pattern str
26690 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ing.** does not 
266a0 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d  need to be recom
266b0 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e  piled on each in
266c0 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  vocation..**.** 
266d0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
266e0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
266f0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
26700 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
26710 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
26720 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
26730 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
26740 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
26750 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
26760 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
26770 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
26780 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 49 66  ned function. If
26790 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73   no metadata has
267a0 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65   been ever.** be
267b0 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e  en set for the N
267c0 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  th argument of t
267d0 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20  he function, or 
267e0 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  if the correspon
267f0 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ding.** function
26800 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63   parameter has c
26810 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65  hanged since the
26820 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73   meta-data was s
26830 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  et,.** then sqli
26840 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
26850 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
26860 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
26870 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
26880 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
26890 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
268a0 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
268b0 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
268c0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
268d0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
268e0 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
268f0 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
26900 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26910 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
26920 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
26930 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
26940 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
26950 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
26960 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
26970 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
26980 2a 20 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e  * If it is not N
26990 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
269a0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
269b0 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
269c0 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
269d0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
269e0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
269f0 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
26a00 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
26a10 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
26a20 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
26a30 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
26a40 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
26a50 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
26a60 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
26a70 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
26a80 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
26a90 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
26aa0 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
26ab0 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
26ac0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
26ad0 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
26ae0 61 6e 79 20 74 69 6d 65 2e 20 20 54 68 65 20 6f  any time.  The o
26af0 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
26b00 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
26b10 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
26b20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
26b30 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
26b40 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  opped..**.** In 
26b50 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
26b60 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
26b70 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
26b80 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
26b90 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
26ba0 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
26bb0 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
26bc0 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
26bd0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
26be0 20 53 51 4c 20 76 61 72 69 61 62 6c 65 73 2e 0a   SQL variables..
26bf0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
26c00 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
26c10 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
26c20 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
26c30 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
26c40 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
26c50 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
26c60 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 32 37 32  ents:.** [H16272
26c70 5d 20 5b 48 31 36 32 37 34 5d 20 5b 48 31 36 32  ] [H16274] [H162
26c80 37 36 5d 20 5b 48 31 36 32 37 37 5d 20 5b 48 31  76] [H16277] [H1
26c90 36 32 37 38 5d 20 5b 48 31 36 32 37 39 5d 0a 2a  6278] [H16279].*
26ca0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
26cb0 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
26cc0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
26cd0 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t N);.void sqlit
26ce0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73  e3_set_auxdata(s
26cf0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
26d00 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76   int N, void*, v
26d10 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b  oid (*)(void*));
26d20 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
26d30 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66  F: Constants Def
26d40 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65  ining Special De
26d50 73 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f  structor Behavio
26d60 72 20 7b 48 31 30 32 38 30 7d 20 3c 53 33 30 31  r {H10280} <S301
26d70 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  00>.**.** These 
26d80 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
26d90 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
26da0 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
26db0 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
26dc0 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
26dd0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
26de0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
26df0 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 49 66 20 74  t_blob()].  If t
26e00 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
26e10 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c   argument is SQL
26e20 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d  ITE_STATIC, it m
26e30 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
26e40 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73  ntent pointer is
26e50 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64   constant.** and
26e60 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e   will never chan
26e70 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74  ge.  It does not
26e80 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73 74   need to be dest
26e90 72 6f 79 65 64 2e 20 20 54 68 65 0a 2a 2a 20 53  royed.  The.** S
26ea0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
26eb0 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74  value means that
26ec0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c   the content wil
26ed0 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20  l likely change 
26ee0 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66  in.** the near f
26ef0 75 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53  uture and that S
26f00 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b  QLite should mak
26f10 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  e its own privat
26f20 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  e copy of.** the
26f30 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20   content before 
26f40 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
26f50 20 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20   The typedef is 
26f60 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72  necessary to wor
26f70 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d  k around problem
26f80 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20  s in certain.** 
26f90 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20  C++ compilers.  
26fa0 53 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31  See ticket #2191
26fb0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69  ..*/.typedef voi
26fc0 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74  d (*sqlite3_dest
26fd0 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69  ructor_type)(voi
26fe0 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  d*);.#define SQL
26ff0 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20  ITE_STATIC      
27000 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
27010 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65  ctor_type)0).#de
27020 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
27030 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65  SIENT   ((sqlite
27040 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
27050 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e)-1)../*.** CAP
27060 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54  I3REF: Setting T
27070 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20  he Result Of An 
27080 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 7b 48 31  SQL Function {H1
27090 36 34 30 30 7d 20 3c 53 32 30 32 30 30 3e 0a 2a  6400} <S20200>.*
270a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
270b0 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
270c0 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
270d0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
270e0 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
270f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
27100 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
27110 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
27120 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
27130 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
27140 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
27150 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
27160 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
27170 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
27180 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
27190 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
271a0 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
271b0 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
271c0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
271d0 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
271e0 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
271f0 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
27200 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
27210 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
27220 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
27230 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
27240 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
27250 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
27260 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
27270 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
27280 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
27290 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
272a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
272b0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
272c0 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
272d0 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
272e0 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
272f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
27300 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
27310 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
27320 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
27330 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
27340 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
27350 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e  lt_zeroblob() in
27360 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65  terfaces set the
27370 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
27380 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
27390 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
273a0 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74  o be a BLOB cont
273b0 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a  aining all zero.
273c0 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ** bytes and N b
273d0 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68  ytes in size, wh
273e0 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c  ere N is the val
273f0 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61  ue of the 2nd pa
27400 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  rameter..**.** T
27410 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
27420 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
27430 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
27440 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
27450 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27460 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
27470 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
27480 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
27490 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
274a0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
274b0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
274c0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
274d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
274e0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
274f0 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
27500 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
27510 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
27520 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
27530 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
27540 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
27550 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
27560 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
27570 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
27580 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
27590 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
275a0 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
275b0 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
275c0 65 73 73 61 67 65 2e 20 20 53 51 4c 69 74 65 20  essage.  SQLite 
275d0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
275e0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
275f0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
27600 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
27610 28 29 20 61 73 20 55 54 46 2d 38 2e 20 53 51 4c  () as UTF-8. SQL
27620 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
27630 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
27640 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
27650 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
27660 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
27670 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 49  * byte order.  I
27680 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
27690 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
276a0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
276b0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
276c0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
276d0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
276e0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
276f0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
27700 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
27710 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
27720 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
27730 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 74 68 69  r..** If the thi
27740 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
27750 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27760 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
27770 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
27780 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
27790 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
277a0 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
277b0 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
277c0 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
277d0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
277e0 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
277f0 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 54 68 65 20  message..** The 
27800 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
27810 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
27820 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
27830 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
27840 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
27850 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
27860 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
27870 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
27880 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
27890 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
278a0 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
278b0 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
278c0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
278d0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
278e0 20 68 61 72 6d 2e 0a 2a 2a 20 54 68 65 20 73 71   harm..** The sq
278f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
27900 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
27910 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
27920 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
27930 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
27940 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
27950 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
27960 63 74 69 6f 6e 2e 20 20 42 79 20 64 65 66 61 75  ction.  By defau
27970 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
27980 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
27990 45 52 52 4f 52 2e 20 20 41 20 73 75 62 73 65 71  ERROR.  A subseq
279a0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
279b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
279c0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
279d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
279e0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
279f0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
27a00 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
27a10 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
27a20 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
27a30 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
27a40 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
27a50 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
27a60 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
27a70 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 20  g or BLOB is to 
27a80 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
27a90 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  t..**.** The sql
27aa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65  ite3_result_nome
27ab0 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  m() interface ca
27ac0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
27ad0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
27ae0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
27af0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
27b00 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a  tion failed..**.
27b10 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
27b20 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
27b30 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
27b40 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
27b50 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
27b60 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
27b70 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
27b80 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
27b90 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
27ba0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
27bb0 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 73 71  ument..** The sq
27bc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
27bd0 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
27be0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
27bf0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
27c00 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
27c10 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
27c20 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
27c30 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
27c40 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
27c50 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
27c60 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27c70 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
27c80 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
27c90 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
27ca0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
27cb0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
27cc0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
27cd0 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  L..**.** The sql
27ce0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
27cf0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
27d00 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
27d10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
27d20 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
27d30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
27d40 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
27d50 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
27d60 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
27d70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
27d80 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
27d90 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
27da0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
27db0 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
27dc0 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
27dd0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
27de0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
27df0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
27e00 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
27e10 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
27e20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
27e30 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
27e40 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
27e50 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
27e60 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
27e70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
27e80 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
27e90 65 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  es..** If the 3r
27ea0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
27eb0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
27ec0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
27ed0 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
27ee0 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
27ef0 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
27f00 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
27f10 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
27f20 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
27f30 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
27f40 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
27f50 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
27f60 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
27f70 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
27f80 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
27f90 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
27fa0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
27fb0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
27fc0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
27fd0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
27fe0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
27ff0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
28000 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
28010 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 49  ion result..** I
28020 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
28030 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
28040 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
28050 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
28060 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28070 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
28080 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
28090 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
280a0 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
280b0 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
280c0 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
280d0 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
280e0 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
280f0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
28100 65 73 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65  esult..** If the
28110 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
28120 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
28130 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
28140 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73  faces or to.** s
28150 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
28160 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
28170 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
28180 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
28190 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
281a0 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
281b0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
281c0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
281d0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
281e0 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74  ** copy the cont
281f0 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d  ent of the param
28200 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20  eter nor call a 
28210 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
28220 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65  e content.** whe
28230 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
28240 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
28250 75 6c 74 2e 0a 2a 2a 20 49 66 20 74 68 65 20 34  ult..** If the 4
28260 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
28270 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
28280 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
28290 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
282a0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
282b0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
282c0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
282d0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
282e0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
282f0 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
28300 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
28310 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
28320 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
28330 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
28340 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  eturns..**.** Th
28350 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
28360 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
28370 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
28380 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
28390 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
283a0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
283b0 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75  a copy the.** [u
283c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
283d0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
283e0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
283f0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
28400 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
28410 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
28420 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
28430 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
28440 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
28450 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
28460 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
28470 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
28480 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
28490 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
284a0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
284b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
284c0 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
284d0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 41 20  hout harm..** A 
284e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
284f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
28500 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75   may always be u
28510 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20  sed where an.** 
28520 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
28530 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
28540 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20  ct is required, 
28550 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e  so either.** kin
28560 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61  d of [sqlite3_va
28570 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20  lue] object can 
28580 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69  be used with thi
28590 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
285a0 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74  ** If these rout
285b0 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
285c0 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20  from within the 
285d0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
285e0 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  .** than the one
285f0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
28600 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
28610 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ned function tha
28620 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68  t received.** th
28630 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  e [sqlite3_conte
28640 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  xt] pointer, the
28650 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
28660 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  efined..**.** Re
28670 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
28680 48 31 36 34 30 33 5d 20 5b 48 31 36 34 30 36 5d  H16403] [H16406]
28690 20 5b 48 31 36 34 30 39 5d 20 5b 48 31 36 34 31   [H16409] [H1641
286a0 32 5d 20 5b 48 31 36 34 31 35 5d 20 5b 48 31 36  2] [H16415] [H16
286b0 34 31 38 5d 20 5b 48 31 36 34 32 31 5d 20 5b 48  418] [H16421] [H
286c0 31 36 34 32 34 5d 0a 2a 2a 20 5b 48 31 36 34 32  16424].** [H1642
286d0 37 5d 20 5b 48 31 36 34 33 30 5d 20 5b 48 31 36  7] [H16430] [H16
286e0 34 33 33 5d 20 5b 48 31 36 34 33 36 5d 20 5b 48  433] [H16436] [H
286f0 31 36 34 33 39 5d 20 5b 48 31 36 34 34 32 5d 20  16439] [H16442] 
28700 5b 48 31 36 34 34 35 5d 20 5b 48 31 36 34 34 38  [H16445] [H16448
28710 5d 0a 2a 2a 20 5b 48 31 36 34 35 31 5d 20 5b 48  ].** [H16451] [H
28720 31 36 34 35 34 5d 20 5b 48 31 36 34 35 37 5d 20  16454] [H16457] 
28730 5b 48 31 36 34 36 30 5d 20 5b 48 31 36 34 36 33  [H16460] [H16463
28740 5d 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ].*/.void sqlite
28750 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
28760 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
28770 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
28780 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
28790 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
287a0 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
287b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
287c0 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71  double);.void sq
287d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
287e0 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
287f0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
28800 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
28810 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
28820 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  r16(sqlite3_cont
28830 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
28840 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
28850 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
28860 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65  or_toobig(sqlite
28870 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
28880 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
28890 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
288a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
288b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
288c0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
288d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
288e0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
288f0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73  te3_result_int(s
28900 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
28910 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
28920 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
28930 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28940 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
28950 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
28960 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
28970 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
28980 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
28990 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  lt_text(sqlite3_
289a0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
289b0 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  char*, int, void
289c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
289d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
289e0 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
289f0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
28a00 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
28a10 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
28a20 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
28a30 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
28a40 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
28a50 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
28a60 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
28a70 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
28a80 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  t_text16be(sqlit
28a90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
28aa0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
28ab0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
28ac0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
28ad0 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  lt_value(sqlite3
28ae0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
28af0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
28b00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28b10 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
28b20 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
28b30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28b40 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
28b50 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
28b60 65 73 20 7b 48 31 36 36 30 30 7d 20 3c 53 32 30  es {H16600} <S20
28b70 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  300>.**.** These
28b80 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 75   functions are u
28b90 73 65 64 20 74 6f 20 61 64 64 20 6e 65 77 20 63  sed to add new c
28ba0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
28bb0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 64 61  es to the.** [da
28bc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28bd0 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
28be0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
28bf0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  nt..**.** The na
28c00 6d 65 20 6f 66 20 74 68 65 20 6e 65 77 20 63 6f  me of the new co
28c10 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
28c20 20 69 73 20 73 70 65 63 69 66 69 65 64 20 61 73   is specified as
28c30 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
28c40 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
28c50 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
28c60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
28c70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
28c80 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
28c90 2d 31 36 20 73 74 72 69 6e 67 20 66 6f 72 20 73  -16 string for s
28ca0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
28cb0 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 20 49 6e 20  llation16(). In 
28cc0 61 6c 6c 20 63 61 73 65 73 0a 2a 2a 20 74 68 65  all cases.** the
28cd0 20 6e 61 6d 65 20 69 73 20 70 61 73 73 65 64 20   name is passed 
28ce0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75  as the second fu
28cf0 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
28d00 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64  .**.** The third
28d10 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65   argument may be
28d20 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
28d30 74 61 6e 74 73 20 5b 53 51 4c 49 54 45 5f 55 54  tants [SQLITE_UT
28d40 46 38 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  F8],.** [SQLITE_
28d50 55 54 46 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51  UTF16LE], or [SQ
28d60 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 69  LITE_UTF16BE], i
28d70 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 74  ndicating that t
28d80 68 65 20 75 73 65 72 2d 73 75 70 70 6c 69 65 64  he user-supplied
28d90 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 65 78 70 65  .** routine expe
28da0 63 74 73 20 74 6f 20 62 65 20 70 61 73 73 65 64  cts to be passed
28db0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
28dc0 69 6e 67 73 20 65 6e 63 6f 64 65 64 20 75 73 69  ings encoded usi
28dd0 6e 67 20 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46  ng UTF-8,.** UTF
28de0 2d 31 36 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  -16 little-endia
28df0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
28e00 2d 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74  -endian, respect
28e10 69 76 65 6c 79 2e 20 54 68 65 0a 2a 2a 20 74 68  ively. The.** th
28e20 69 72 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67  ird argument mig
28e30 68 74 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49  ht also be [SQLI
28e40 54 45 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e 64  TE_UTF16] to ind
28e50 69 63 61 74 65 20 74 68 61 74 20 74 68 65 20 72  icate that the r
28e60 6f 75 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74  outine.** expect
28e70 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 65  s pointers to be
28e80 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
28e90 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
28ea0 74 65 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 65  te order, or the
28eb0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 6e  .** argument can
28ec0 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
28ed0 36 5f 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 68  6_ALIGNED] if th
28ee0 65 0a 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65  e.** the routine
28ef0 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72   expects pointer
28f00 73 20 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64  s to 16-bit word
28f10 20 61 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73   aligned strings
28f20 0a 2a 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e  .** of UTF-16 in
28f30 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
28f40 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20   order..**.** A 
28f50 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75  pointer to the u
28f60 73 65 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75  ser supplied rou
28f70 74 69 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73  tine must be pas
28f80 73 65 64 20 61 73 20 74 68 65 20 66 69 66 74 68  sed as the fifth
28f90 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 49  .** argument.  I
28fa0 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  f it is NULL, th
28fb0 69 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  is is the same a
28fc0 73 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  s deleting the c
28fd0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
28fe0 65 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51  ence (so that SQ
28ff0 4c 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c  Lite cannot call
29000 20 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a   it anymore)..**
29010 20 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61   Each time the a
29020 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c  pplication suppl
29030 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ied function is 
29040 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70  invoked, it is p
29050 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20  assed.** as its 
29060 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
29070 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
29080 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  id* passed as th
29090 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
290a0 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
290b0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
290c0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
290d0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
290e0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65  ()..**.** The re
290f0 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74  maining argument
29100 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  s to the applica
29110 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f  tion-supplied ro
29120 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74  utine are two st
29130 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72  rings,.** each r
29140 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20  epresented by a 
29150 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70  (length, data) p
29160 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20  air and encoded 
29170 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a  in the encoding.
29180 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73  ** that was pass
29190 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
291a0 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68  argument when th
291b0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  e collation sequ
291c0 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69  ence was.** regi
291d0 73 74 65 72 65 64 2e 20 7b 45 4e 44 7d 20 20 54  stered. {END}  T
291e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
291f0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
29200 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 0a   routine should.
29210 2a 2a 20 72 65 74 75 72 6e 20 6e 65 67 61 74 69  ** return negati
29220 76 65 2c 20 7a 65 72 6f 20 6f 72 20 70 6f 73 69  ve, zero or posi
29230 74 69 76 65 20 69 66 20 74 68 65 20 66 69 72 73  tive if the firs
29240 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73  t string is less
29250 20 74 68 61 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20   than,.** equal 
29260 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74  to, or greater t
29270 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 20 73  han the second s
29280 74 72 69 6e 67 2e 20 69 2e 65 2e 20 28 53 54 52  tring. i.e. (STR
29290 49 4e 47 31 20 2d 20 53 54 52 49 4e 47 32 29 2e  ING1 - STRING2).
292a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
292b0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
292c0 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c  ion_v2() works l
292d0 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ike sqlite3_crea
292e0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a  te_collation().*
292f0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
29300 20 74 61 6b 65 73 20 61 6e 20 65 78 74 72 61 20   takes an extra 
29310 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
29320 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  s a destructor f
29330 6f 72 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  or.** the collat
29340 69 6f 6e 2e 20 20 54 68 65 20 64 65 73 74 72 75  ion.  The destru
29350 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77  ctor is called w
29360 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f  hen the collatio
29370 6e 20 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65  n is.** destroye
29380 64 20 61 6e 64 20 69 73 20 70 61 73 73 65 64 20  d and is passed 
29390 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f  a copy of the fo
293a0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 76  urth parameter v
293b0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  oid* pointer.** 
293c0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
293d0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
293e0 76 32 28 29 2e 0a 2a 2a 20 43 6f 6c 6c 61 74 69  v2()..** Collati
293f0 6f 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65  ons are destroye
29400 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
29410 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
29420 74 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  ter calls to the
29430 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  .** collation cr
29440 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
29450 20 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61   or when the [da
29460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29470 6e 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20  n] is closed.** 
29480 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
29490 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  lose()]..**.** S
294a0 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74  ee also:  [sqlit
294b0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
294c0 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ded()] and [sqli
294d0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
294e0 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  eded16()]..**.**
294f0 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a   Requirements:.*
29500 2a 20 5b 48 31 36 36 30 33 5d 20 5b 48 31 36 36  * [H16603] [H166
29510 30 34 5d 20 5b 48 31 36 36 30 36 5d 20 5b 48 31  04] [H16606] [H1
29520 36 36 30 39 5d 20 5b 48 31 36 36 31 32 5d 20 5b  6609] [H16612] [
29530 48 31 36 36 31 35 5d 20 5b 48 31 36 36 31 38 5d  H16615] [H16618]
29540 20 5b 48 31 36 36 32 31 5d 0a 2a 2a 20 5b 48 31   [H16621].** [H1
29550 36 36 32 34 5d 20 5b 48 31 36 36 32 37 5d 20 5b  6624] [H16627] [
29560 48 31 36 36 33 30 5d 0a 2a 2f 0a 69 6e 74 20 73  H16630].*/.int s
29570 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
29580 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
29590 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
295a0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
295b0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
295c0 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  oid*,.  int(*xCo
295d0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
295e0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
295f0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
29600 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
29610 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
29620 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
29630 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
29640 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
29650 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
29660 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
29670 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
29680 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
29690 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  void*),.  void(*
296a0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
296b0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
296c0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
296d0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
296e0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
296f0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
29700 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
29710 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
29720 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
29730 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
29740 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
29750 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
29760 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
29770 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30 7d 20  lbacks {H16700} 
29780 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a 20 54  <S20300>.**.** T
29790 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
297a0 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
297b0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
297c0 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
297d0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
297e0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
297f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
29800 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
29810 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
29820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
29830 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64  on] to be called
29840 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
29850 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
29860 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
29870 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
29880 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
29890 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
298a0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
298b0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
298c0 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
298d0 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
298e0 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
298f0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
29900 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
29910 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
29920 20 55 54 46 2d 38 2e 20 7b 48 31 36 37 30 33 7d   UTF-8. {H16703}
29930 20 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   If sqlite3_coll
29940 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
29950 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65   is used,.** the
29960 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73 65   names are passe
29970 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d  d as UTF-16 in m
29980 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79  achine native by
29990 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 41 20 63  te order..** A c
299a0 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75  all to either fu
299b0 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20  nction replaces 
299c0 61 6e 79 20 65 78 69 73 74 69 6e 67 20 63 61 6c  any existing cal
299d0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  lback..**.** Whe
299e0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
299f0 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
29a00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
29a10 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
29a20 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
29a30 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
29a40 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
29a50 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
29a60 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
29a70 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
29a80 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
29a90 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
29aa0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
29ab0 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
29ac0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
29ad0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
29ae0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
29af0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
29b00 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
29b10 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
29b20 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
29b30 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
29b40 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
29b50 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
29b60 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
29b70 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
29b80 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
29b90 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
29ba0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
29bb0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68  back function sh
29bc0 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68  ould register th
29bd0 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74  e desired collat
29be0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
29bf0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
29c00 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  lation()], [sqli
29c10 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
29c20 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
29c30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
29c40 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d  _collation_v2()]
29c50 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
29c60 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 36 37 30 32  ents:.** [H16702
29c70 5d 20 5b 48 31 36 37 30 34 5d 20 5b 48 31 36 37  ] [H16704] [H167
29c80 30 36 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  06].*/.int sqlit
29c90 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
29ca0 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
29cb0 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
29cc0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
29cd0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
29ce0 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
29cf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
29d00 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
29d10 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
29d20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
29d30 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
29d40 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
29d50 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
29d60 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
29d70 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
29d80 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
29d90 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
29da0 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
29db0 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
29dc0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
29dd0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
29de0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
29df0 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
29e00 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
29e10 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
29e20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
29e30 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71  qlite3_key(.  sq
29e40 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
29e50 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
29e60 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
29e70 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
29e80 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
29e90 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
29ea0 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  e key */.);../*.
29eb0 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65  ** Change the ke
29ec0 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74  y on an open dat
29ed0 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63  abase.  If the c
29ee0 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20  urrent database 
29ef0 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70  is not.** encryp
29f00 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e  ted, this routin
29f10 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69  e will encrypt i
29f20 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f  t.  If pNew==0 o
29f30 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a  r nNew==0, the.*
29f40 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65  * database is de
29f50 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  crypted..**.** T
29f60 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65  he code to imple
29f70 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73  ment this API is
29f80 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69   not available i
29f90 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c  n the public rel
29fa0 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ease.** of SQLit
29fb0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
29fc0 33 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74  3_rekey(.  sqlit
29fd0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
29fe0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
29ff0 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65  abase to be reke
2a000 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  yed */.  const v
2a010 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e  oid *pKey, int n
2a020 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e  Key     /* The n
2a030 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  ew key */.);../*
2a040 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
2a050 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
2a060 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
2a070 20 7b 48 31 30 35 33 30 7d 20 3c 53 34 30 34 31   {H10530} <S4041
2a080 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2a090 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e  ite3_sleep() fun
2a0a0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65  ction causes the
2a0b0 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20   current thread 
2a0c0 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75  to suspend execu
2a0d0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c  tion.** for at l
2a0e0 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66  east a number of
2a0f0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70   milliseconds sp
2a100 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70  ecified in its p
2a110 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2a120 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  If the operating
2a130 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74   system does not
2a140 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72   support sleep r
2a150 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20  equests with.** 
2a160 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65  millisecond time
2a170 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65   resolution, the
2a180 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20  n the time will 
2a190 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f  be rounded up to
2a1a0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20  .** the nearest 
2a1b0 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62  second. The numb
2a1c0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
2a1d0 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
2a1e0 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
2a1f0 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
2a200 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
2a210 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
2a220 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
2a230 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2a240 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
2a250 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
2a260 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
2a270 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
2a280 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 52 65 71  bject..**.** Req
2a290 75 69 72 65 6d 65 6e 74 73 3a 20 5b 48 31 30 35  uirements: [H105
2a2a0 33 33 5d 20 5b 48 31 30 35 33 36 5d 0a 2a 2f 0a  33] [H10536].*/.
2a2b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  int sqlite3_slee
2a2c0 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  p(int);../*.** C
2a2d0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
2a2e0 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
2a2f0 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
2a300 6c 65 73 20 7b 48 31 30 33 31 30 7d 20 3c 53 32  les {H10310} <S2
2a310 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  0000>.**.** If t
2a320 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
2a330 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
2a340 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
2a350 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
2a360 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
2a370 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
2a380 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
2a390 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
2a3a0 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
2a3b0 69 74 65 20 77 69 6c 6c 20 62 65 20 70 6c 61 63  ite will be plac
2a3c0 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65 63  ed in that direc
2a3d0 74 6f 72 79 2e 20 20 49 66 20 74 68 69 73 20 76  tory.  If this v
2a3e0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20  ariable.** is a 
2a3f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
2a400 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72  en SQLite perfor
2a410 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  ms a search for 
2a420 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a  an appropriate.*
2a430 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
2a440 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
2a450 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
2a460 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
2a470 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
2a480 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e   in more than on
2a490 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61  e.** thread at a
2a4a0 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f   time.  It is no
2a4b0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
2a4c0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
2a4d0 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b  riable.** if a [
2a4e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a4f0 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73  ion] is being us
2a500 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ed at the same t
2a510 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74  ime in a separat
2a520 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20  e.** thread..** 
2a530 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  It is intended t
2a540 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
2a550 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a  e be set once.**
2a560 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63   as part of proc
2a570 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
2a580 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e  on and before an
2a590 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
2a5a0 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68  ce.** routines h
2a5b0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
2a5c0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61  and that this va
2a5d0 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e  riable remain un
2a5e0 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65  changed.** there
2a5f0 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  after..**.** The
2a600 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
2a610 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d  ectory pragma] m
2a620 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  ay modify this v
2a630 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73  ariable and caus
2a640 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74  e.** it to point
2a650 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
2a660 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2a670 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 46 75 72 74  3_malloc].  Furt
2a680 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
2a690 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
2a6a0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c  ctory pragma] al
2a6b0 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61  ways assumes tha
2a6c0 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20  t any string.** 
2a6d0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
2a6e0 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
2a6f0 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  held in memory o
2a700 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
2a710 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2a720 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61  ] and the pragma
2a730 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
2a740 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79  free that memory
2a750 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2a760 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e  e3_free]..** Hen
2a770 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69  ce, if this vari
2a780 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64  able is modified
2a790 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65   directly, eithe
2a7a0 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  r it should be.*
2a7b0 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d  * made NULL or m
2a7c0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
2a7d0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2a7e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
2a7f0 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65  lloc].** or else
2a800 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   the use of the 
2a810 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
2a820 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68  ctory pragma] sh
2a830 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
2a840 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45 52  .*/.SQLITE_EXTER
2a850 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
2a860 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
2a870 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a880 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d 43   Test For Auto-C
2a890 6f 6d 6d 69 74 20 4d 6f 64 65 20 7b 48 31 32 39  ommit Mode {H129
2a8a0 33 30 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20  30} <S60200>.** 
2a8b0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63  KEYWORDS: {autoc
2a8c0 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  ommit mode}.**.*
2a8d0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
2a8e0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69  t_autocommit() i
2a8f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2a900 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
2a910 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
2a920 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
2a930 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
2a940 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
2a950 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63   mode,.** respec
2a960 74 69 76 65 6c 79 2e 20 20 41 75 74 6f 63 6f 6d  tively.  Autocom
2a970 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20 62  mit mode is on b
2a980 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 41 75  y default..** Au
2a990 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2a9a0 20 64 69 73 61 62 6c 65 64 20 62 79 20 61 20 5b   disabled by a [
2a9b0 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74  BEGIN] statement
2a9c0 2e 0a 2a 2a 20 41 75 74 6f 63 6f 6d 6d 69 74 20  ..** Autocommit 
2a9d0 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c  mode is re-enabl
2a9e0 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d  ed by a [COMMIT]
2a9f0 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a   or [ROLLBACK]..
2aa00 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e  **.** If certain
2aa10 20 6b 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73   kinds of errors
2aa20 20 6f 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74   occur on a stat
2aa30 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d  ement within a m
2aa40 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a  ulti-statement.*
2aa50 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65  * transaction (e
2aa60 72 72 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20  rrors including 
2aa70 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b  [SQLITE_FULL], [
2aa80 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a  SQLITE_IOERR],.*
2aa90 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
2aaa0 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  , [SQLITE_BUSY],
2aab0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54   and [SQLITE_INT
2aac0 45 52 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68  ERRUPT]) then th
2aad0 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  e.** transaction
2aae0 20 6d 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64   might be rolled
2aaf0 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
2ab00 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77  lly.  The only w
2ab10 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75  ay to.** find ou
2ab20 74 20 77 68 65 74 68 65 72 20 53 51 4c 69 74 65  t whether SQLite
2ab30 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
2ab40 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74  olled back the t
2ab50 72 61 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72  ransaction after
2ab60 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20  .** an error is 
2ab70 74 6f 20 75 73 65 20 74 68 69 73 20 66 75 6e 63  to use this func
2ab80 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  tion..**.** If a
2ab90 6e 6f 74 68 65 72 20 74 68 72 65 61 64 20 63 68  nother thread ch
2aba0 61 6e 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f  anges the autoco
2abb0 6d 6d 69 74 20 73 74 61 74 75 73 20 6f 66 20 74  mmit status of t
2abc0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
2abd0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
2abe0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
2abf0 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68  running, then th
2ac00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2ac10 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
2ac20 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
2ac30 74 73 3a 20 5b 48 31 32 39 33 31 5d 20 5b 48 31  ts: [H12931] [H1
2ac40 32 39 33 32 5d 20 5b 48 31 32 39 33 33 5d 20 5b  2932] [H12933] [
2ac50 48 31 32 39 33 34 5d 0a 2a 2f 0a 69 6e 74 20 73  H12934].*/.int s
2ac60 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
2ac70 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
2ac80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac90 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62  : Find The Datab
2aca0 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
2acb0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2acc0 6e 74 20 7b 48 31 33 31 32 30 7d 20 3c 53 36 30  nt {H13120} <S60
2acd0 36 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  600>.**.** The s
2ace0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
2acf0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ad00 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ns the [database
2ad10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
2ad20 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20  dle.** to which 
2ad30 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2ad40 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20  ement] belongs. 
2ad50 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
2ad60 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65  onnection].** re
2ad70 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2ad80 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
2ad90 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2ada0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
2adb0 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74  at was the first
2adc0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
2add0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
2ade0 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20  pare_v2()] call 
2adf0 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73  (or its variants
2ae00 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  ) that was used 
2ae10 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65  to.** create the
2ae20 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
2ae30 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
2ae40 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2ae50 73 3a 20 5b 48 31 33 31 32 33 5d 0a 2a 2f 0a 73  s: [H13123].*/.s
2ae60 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
2ae70 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
2ae80 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2ae90 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20   CAPI3REF: Find 
2aea0 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65  the next prepare
2aeb0 64 20 73 74 61 74 65 6d 65 6e 74 20 7b 48 31 33  d statement {H13
2aec0 31 34 30 7d 20 3c 53 36 30 36 30 30 3e 0a 2a 2a  140} <S60600>.**
2aed0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2aee0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2aef0 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74  nter to the next
2af00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2af10 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70  ment] after.** p
2af20 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20  Stmt associated 
2af30 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
2af40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
2af50 44 62 2e 20 20 49 66 20 70 53 74 6d 74 20 69 73  Db.  If pStmt is
2af60 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68   NULL.** then th
2af70 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  is interface ret
2af80 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2af90 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70  o the first prep
2afa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
2afb0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
2afc0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  h the database c
2afd0 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20  onnection pDb.  
2afe0 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73  If no prepared s
2aff0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69  tatement.** sati
2b000 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74  sfies the condit
2b010 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75  ions of this rou
2b020 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73  tine, it returns
2b030 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
2b040 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2b050 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44  ction] pointer D
2b060 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
2b070 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2b080 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72  tmt(D,S)] must r
2b090 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20  efer to an open 
2b0a0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2b0b0 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61  ection and in pa
2b0c0 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f  rticular must no
2b0d0 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t be a NULL poin
2b0e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ter..**.** Requi
2b0f0 72 65 6d 65 6e 74 73 3a 20 5b 48 31 33 31 34 33  rements: [H13143
2b100 5d 20 5b 48 31 33 31 34 36 5d 20 5b 48 31 33 31  ] [H13146] [H131
2b110 34 39 5d 20 5b 48 31 33 31 35 32 5d 0a 2a 2f 0a  49] [H13152].*/.
2b120 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71  sqlite3_stmt *sq
2b130 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2b140 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71  sqlite3 *pDb, sq
2b150 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2b160 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b170 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
2b180 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
2b190 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 20  ation Callbacks 
2b1a0 7b 48 31 32 39 35 30 7d 20 3c 53 36 30 34 30 30  {H12950} <S60400
2b1b0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
2b1c0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2b1d0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
2b1e0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
2b1f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
2b200 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2b210 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
2b220 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63  n is [COMMIT | c
2b230 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 41 6e  ommitted]..** An
2b240 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2b250 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2b260 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
2b270 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
2b280 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
2b290 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2b2a0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
2b2b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c   The sqlite3_rol
2b2c0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
2b2d0 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2b2e0 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
2b2f0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
2b300 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2b310 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2b320 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
2b330 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 41 6e 79  ed back]..** Any
2b340 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2b350 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2b360 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
2b370 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
2b380 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2b390 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2b3a0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2b3b0 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
2b3c0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
2b3d0 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ugh to the callb
2b3e0 61 63 6b 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ack..** If the c
2b3f0 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d  allback on a com
2b400 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f  mit hook functio
2b410 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  n returns non-ze
2b420 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ro,.** then the 
2b430 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72  commit is conver
2b440 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62  ted into a rollb
2b450 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ack..**.** If an
2b460 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 77  other function w
2b470 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  as previously re
2b480 67 69 73 74 65 72 65 64 2c 20 69 74 73 0a 2a 2a  gistered, its.**
2b490 20 70 41 72 67 20 76 61 6c 75 65 20 69 73 20 72   pArg value is r
2b4a0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
2b4b0 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  ise NULL is retu
2b4c0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
2b4d0 63 61 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65  callback impleme
2b4e0 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
2b4f0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
2b500 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
2b510 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b520 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
2b530 76 6f 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61  voked the callba
2b540 63 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73  ck.  Any actions
2b550 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68  .** to modify th
2b560 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2b570 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65  ction must be de
2b580 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74  ferred until aft
2b590 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  er the.** comple
2b5a0 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c  tion of the [sql
2b5b0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
2b5c0 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
2b5d0 20 74 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f   the commit.** o
2b5e0 72 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  r rollback hook 
2b5f0 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
2b600 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ce..** Note that
2b610 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b620 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2b630 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
2b640 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
2b650 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
2b660 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
2b670 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
2b680 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
2b690 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69  raph..**.** Regi
2b6a0 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66  stering a NULL f
2b6b0 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73  unction disables
2b6c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2b6d0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 6f  *.** When the co
2b6e0 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  mmit hook callba
2b6f0 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ck routine retur
2b700 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f  ns zero, the [CO
2b710 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69  MMIT].** operati
2b720 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f  on is allowed to
2b730 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c   continue normal
2b740 6c 79 2e 20 20 49 66 20 74 68 65 20 63 6f 6d 6d  ly.  If the comm
2b750 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72  it hook.** retur
2b760 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
2b770 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69  n the [COMMIT] i
2b780 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
2b790 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a   a [ROLLBACK]..*
2b7a0 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68  * The rollback h
2b7b0 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ook is invoked o
2b7c0 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61  n a rollback tha
2b7d0 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61  t results from a
2b7e0 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20   commit.** hook 
2b7f0 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65  returning non-ze
2b800 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77  ro, just as it w
2b810 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79  ould be with any
2b820 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e   other rollback.
2b830 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 74 68 65 20 70  .**.** For the p
2b840 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
2b850 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69  API, a transacti
2b860 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  on is said to ha
2b870 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65  ve been.** rolle
2b880 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70  d back if an exp
2b890 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22  licit "ROLLBACK"
2b8a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78   statement is ex
2b8b0 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e  ecuted, or.** an
2b8c0 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72   error or constr
2b8d0 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69  aint causes an i
2b8e0 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b  mplicit rollback
2b8f0 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 54 68   to occur..** Th
2b900 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
2b910 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
2b920 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
2b930 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
2b940 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
2b950 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
2b960 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b970 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
2b980 2a 20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63  * The rollback c
2b990 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
2b9a0 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
2b9b0 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f  saction is.** ro
2b9c0 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
2b9d0 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62  e a commit callb
2b9e0 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e  ack returned non
2b9f0 2d 7a 65 72 6f 2e 0a 2a 2a 20 3c 74 6f 64 6f 3e  -zero..** <todo>
2ba00 20 43 68 65 63 6b 20 6f 6e 20 74 68 69 73 20 3c   Check on this <
2ba10 2f 74 6f 64 6f 3e 0a 2a 2a 0a 2a 2a 20 53 65 65  /todo>.**.** See
2ba20 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
2ba30 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2ba40 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
2ba50 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a  ** Requirements:
2ba60 0a 2a 2a 20 5b 48 31 32 39 35 31 5d 20 5b 48 31  .** [H12951] [H1
2ba70 32 39 35 32 5d 20 5b 48 31 32 39 35 33 5d 20 5b  2952] [H12953] [
2ba80 48 31 32 39 35 34 5d 20 5b 48 31 32 39 35 35 5d  H12954] [H12955]
2ba90 0a 2a 2a 20 5b 48 31 32 39 36 31 5d 20 5b 48 31  .** [H12961] [H1
2baa0 32 39 36 32 5d 20 5b 48 31 32 39 36 33 5d 20 5b  2962] [H12963] [
2bab0 48 31 32 39 36 34 5d 0a 2a 2f 0a 76 6f 69 64 20  H12964].*/.void 
2bac0 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f  *sqlite3_commit_
2bad0 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69  hook(sqlite3*, i
2bae0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
2baf0 69 64 2a 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  id*);.void *sqli
2bb00 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f  te3_rollback_hoo
2bb10 6b 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  k(sqlite3*, void
2bb20 28 2a 29 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69  (*)(void *), voi
2bb30 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
2bb40 33 52 45 46 3a 20 44 61 74 61 20 43 68 61 6e 67  3REF: Data Chang
2bb50 65 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43  e Notification C
2bb60 61 6c 6c 62 61 63 6b 73 20 7b 48 31 32 39 37 30  allbacks {H12970
2bb70 7d 20 3c 53 36 30 34 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60400>.**.**
2bb80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64   The sqlite3_upd
2bb90 61 74 65 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72  ate_hook() inter
2bba0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
2bbb0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2bbc0 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
2bbd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2bbe0 69 6f 6e 5d 20 69 64 65 6e 74 69 66 69 65 64 20  ion] identified 
2bbf0 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
2bc00 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 69  ument.** to be i
2bc10 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2bc20 61 20 72 6f 77 20 69 73 20 75 70 64 61 74 65 64  a row is updated
2bc30 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65  , inserted or de
2bc40 6c 65 74 65 64 2e 0a 2a 2a 20 41 6e 79 20 63 61  leted..** Any ca
2bc50 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
2bc60 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2bc70 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2bc80 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
2bc90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2bca0 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
2bcb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
2bcc0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  nd argument is a
2bcd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2bce0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f  function to invo
2bcf0 6b 65 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77  ke when a.** row
2bd00 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
2bd10 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
2bd20 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
2bd30 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
2bd40 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
2bd50 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61  y of the third a
2bd60 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71  rgument.** to sq
2bd70 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2bd80 6b 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f  k()..** The seco
2bd90 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
2bda0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
2bdb0 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
2bdc0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
2bdd0 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
2bde0 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
2bdf0 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
2be00 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
2be10 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
2be20 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
2be30 20 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66   The third and f
2be40 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
2be50 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
2be60 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
2be70 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
2be80 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61  ase and table na
2be90 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
2bea0 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a  e affected row..
2beb0 2a 2a 20 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  ** The final cal
2bec0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
2bed0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
2bee0 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 49 6e  f the row..** In
2bef0 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20   the case of an 
2bf00 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
2bf10 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65  the [rowid] afte
2bf20 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  r the update tak
2bf30 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
2bf40 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
2bf50 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
2bf60 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
2bf70 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
2bf80 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
2bf90 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
2bfa0 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
2bfb0 63 65 29 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  ce)..**.** In th
2bfc0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
2bfd0 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70  entation, the up
2bfe0 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20  date hook.** is 
2bff0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
2c000 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77   duplication row
2c010 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65  s are deleted be
2c020 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b  cause of an.** [
2c030 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e  ON CONFLICT | ON
2c040 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43   CONFLICT REPLAC
2c050 45 5d 20 63 6c 61 75 73 65 2e 20 20 4e 6f 72 20  E] clause.  Nor 
2c060 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  is the update ho
2c070 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77 68  ok.** invoked wh
2c080 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  en rows are dele
2c090 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 74  ted using the [t
2c0a0 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
2c0b0 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65 78  tion]..** The ex
2c0c0 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65 64  ceptions defined
2c0d0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
2c0e0 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ph might change 
2c0f0 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
2c100 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
2c110 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64 61  ..**.** The upda
2c120 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65 6e  te hook implemen
2c130 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  tation must not 
2c140 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
2c150 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
2c160 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2c170 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
2c180 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65 20  oked the update 
2c190 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69 6f  hook.  Any actio
2c1a0 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79 20  ns.** to modify 
2c1b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2c1c0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  nection must be 
2c1d0 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
2c1e0 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  fter the.** comp
2c1f0 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b 73  letion of the [s
2c200 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2c210 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
2c220 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68 6f  ed the update ho
2c230 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  ok..** Note that
2c240 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c250 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2c260 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
2c270 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
2c280 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
2c290 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
2c2a0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
2c2b0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
2c2c0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  raph..**.** If a
2c2d0 6e 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  nother function 
2c2e0 77 61 73 20 70 72 65 76 69 6f 75 73 6c 79 20 72  was previously r
2c2f0 65 67 69 73 74 65 72 65 64 2c 20 69 74 73 20 70  egistered, its p
2c300 41 72 67 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  Arg value.** is 
2c310 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72  returned.  Other
2c320 77 69 73 65 20 4e 55 4c 4c 20 69 73 20 72 65 74  wise NULL is ret
2c330 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  urned..**.** See
2c340 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
2c350 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2c360 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
2c370 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a  ollback_hook()].
2c380 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  ** interfaces..*
2c390 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e 74  *.** Requirement
2c3a0 73 3a 0a 2a 2a 20 5b 48 31 32 39 37 31 5d 20 5b  s:.** [H12971] [
2c3b0 48 31 32 39 37 33 5d 20 5b 48 31 32 39 37 35 5d  H12973] [H12975]
2c3c0 20 5b 48 31 32 39 37 37 5d 20 5b 48 31 32 39 37   [H12977] [H1297
2c3d0 39 5d 20 5b 48 31 32 39 38 31 5d 20 5b 48 31 32  9] [H12981] [H12
2c3e0 39 38 33 5d 20 5b 48 31 32 39 38 36 5d 0a 2a 2f  983] [H12986].*/
2c3f0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
2c400 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
2c410 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
2c420 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
2c430 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
2c440 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
2c450 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
2c460 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2c470 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
2c480 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
2c490 67 65 72 20 43 61 63 68 65 20 7b 48 31 30 33 33  ger Cache {H1033
2c4a0 30 7d 20 3c 53 33 30 39 30 30 3e 0a 2a 2a 20 4b  0} <S30900>.** K
2c4b0 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64  EYWORDS: {shared
2c4c0 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 54 68   cache}.**.** Th
2c4d0 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
2c4e0 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
2c4f0 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68  he sharing of th
2c500 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65  e database cache
2c510 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64  .** and schema d
2c520 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62  ata structures b
2c530 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65  etween [database
2c540 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f   connection | co
2c550 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f  nnections].** to
2c560 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2c570 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65  se. Sharing is e
2c580 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
2c590 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a  gument is true.*
2c5a0 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  * and disabled i
2c5b0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
2c5c0 73 20 66 61 6c 73 65 2e 0a 2a 2a 0a 2a 2a 20 43  s false..**.** C
2c5d0 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20  ache sharing is 
2c5e0 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61  enabled and disa
2c5f0 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69  bled for an enti
2c600 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54  re process..** T
2c610 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20  his is a change 
2c620 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  as of SQLite ver
2c630 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70  sion 3.5.0. In p
2c640 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  rior versions of
2c650 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72   SQLite,.** shar
2c660 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20  ing was enabled 
2c670 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  or disabled for 
2c680 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61  each thread sepa
2c690 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  rately..**.** Th
2c6a0 65 20 63 61 63 68 65 20 73 68 61 72 69 6e 67 20  e cache sharing 
2c6b0 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68 69 73  mode set by this
2c6c0 20 69 6e 74 65 72 66 61 63 65 20 65 66 66 65 63   interface effec
2c6d0 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  ts all subsequen
2c6e0 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73  t.** calls to [s
2c6f0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2c700 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2c710 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2c720 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20  3_open16()]..** 
2c730 45 78 69 73 74 69 6e 67 20 64 61 74 61 62 61 73  Existing databas
2c740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f  e connections co
2c750 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65 20 73  ntinue use the s
2c760 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74  haring mode.** t
2c770 68 61 74 20 77 61 73 20 69 6e 20 65 66 66 65 63  hat was in effec
2c780 74 20 61 74 20 74 68 65 20 74 69 6d 65 20 74 68  t at the time th
2c790 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64 2e 0a  ey were opened..
2c7a0 2a 2a 0a 2a 2a 20 56 69 72 74 75 61 6c 20 74 61  **.** Virtual ta
2c7b0 62 6c 65 73 20 63 61 6e 6e 6f 74 20 62 65 20 75  bles cannot be u
2c7c0 73 65 64 20 77 69 74 68 20 61 20 73 68 61 72 65  sed with a share
2c7d0 64 20 63 61 63 68 65 2e 20 20 57 68 65 6e 20 73  d cache.  When s
2c7e0 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
2c7f0 73 20 65 6e 61 62 6c 65 64 2c 20 74 68 65 20 5b  s enabled, the [
2c800 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
2c810 6f 64 75 6c 65 28 29 5d 20 41 50 49 20 75 73 65  odule()] API use
2c820 64 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a  d to register.**
2c830 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
2c840 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
2c850 72 6e 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 0a  rn an error..**.
2c860 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2c870 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2c880 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
2c890 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20  che was enabled 
2c8a0 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73  or disabled.** s
2c8b0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e  uccessfully.  An
2c8c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2c8d0 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
2c8e0 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 53 68 61 72 65  ise..**.** Share
2c8f0 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62  d cache is disab
2c900 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20  led by default. 
2c910 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63  But this might c
2c920 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75  hange in.** futu
2c930 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
2c940 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74  QLite.  Applicat
2c950 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61  ions that care a
2c960 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63  bout shared.** c
2c970 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f  ache setting sho
2c980 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69  uld set it expli
2c990 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  citly..**.** See
2c9a0 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20   Also:  [SQLite 
2c9b0 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64  Shared-Cache Mod
2c9c0 65 5d 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65  e].**.** Require
2c9d0 6d 65 6e 74 73 3a 20 5b 48 31 30 33 33 31 5d 20  ments: [H10331] 
2c9e0 5b 48 31 30 33 33 36 5d 20 5b 48 31 30 33 33 37  [H10336] [H10337
2c9f0 5d 20 5b 48 31 30 33 33 39 5d 0a 2a 2f 0a 69 6e  ] [H10339].*/.in
2ca00 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
2ca10 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 69 6e  _shared_cache(in
2ca20 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2ca30 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54 6f 20  REF: Attempt To 
2ca40 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f 72 79  Free Heap Memory
2ca50 20 7b 48 31 37 33 34 30 7d 20 3c 53 33 30 32 32   {H17340} <S3022
2ca60 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  0>.**.** The sql
2ca70 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2ca80 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  ory() interface 
2ca90 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65 65  attempts to free
2caa0 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 68   N bytes.** of h
2cab0 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64 65  eap memory by de
2cac0 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d 65  allocating non-e
2cad0 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 20  ssential memory 
2cae0 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20 68  allocations.** h
2caf0 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61 62  eld by the datab
2cb00 61 73 65 20 6c 69 62 72 61 72 79 2e 20 7b 45 4e  ase library. {EN
2cb10 44 7d 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20  D}  Memory used 
2cb20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
2cb30 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d  e.** pages to im
2cb40 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
2cb50 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  e is an example 
2cb60 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  of non-essential
2cb70 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 73 71 6c 69   memory..** sqli
2cb80 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2cb90 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65  ry() returns the
2cba0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2cbb0 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c   actually freed,
2cbc0 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20  .** which might 
2cbd0 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20  be more or less 
2cbe0 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20  than the amount 
2cbf0 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 0a 2a 2a  requested..**.**
2cc00 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 20 5b   Requirements: [
2cc10 48 31 37 33 34 31 5d 20 5b 48 31 37 33 34 32 5d  H17341] [H17342]
2cc20 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2cc30 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69  release_memory(i
2cc40 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2cc50 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c  3REF: Impose A L
2cc60 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a  imit On Heap Siz
2cc70 65 20 7b 48 31 37 33 35 30 7d 20 3c 53 33 30 32  e {H17350} <S302
2cc80 32 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  20>.**.** The sq
2cc90 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
2cca0 6c 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  limit() interfac
2ccb0 65 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74  e places a "soft
2ccc0 22 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68  " limit.** on th
2ccd0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
2cce0 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
2ccf0 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   be allocated by
2cd00 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 49 66 20 61   SQLite..** If a
2cd10 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63  n internal alloc
2cd20 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
2cd30 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78  ed that would ex
2cd40 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74  ceed the.** soft
2cd50 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71   heap limit, [sq
2cd60 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2cd70 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b  mory()] is invok
2cd80 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72  ed one or.** mor
2cd90 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20  e times to free 
2cda0 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65  up some space be
2cdb0 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  fore the allocat
2cdc0 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
2cdd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 6d 69  ..**.** The limi
2cde0 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66  t is called "sof
2cdf0 74 22 2c 20 62 65 63 61 75 73 65 20 69 66 20 5b  t", because if [
2ce00 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2ce10 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e  memory()].** can
2ce20 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69  not free suffici
2ce30 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72  ent memory to pr
2ce40 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20  event the limit 
2ce50 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65  from being excee
2ce60 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  ded,.** the memo
2ce70 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20  ry is allocated 
2ce80 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63  anyway and the c
2ce90 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
2cea0 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a   proceeds..**.**
2ceb0 20 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a   A negative or z
2cec0 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20  ero value for N 
2ced0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
2cee0 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70   is no soft heap
2cef0 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73   limit and.** [s
2cf00 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2cf10 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
2cf20 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2cf30 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61  n memory is exha
2cf40 75 73 74 65 64 2e 0a 2a 2a 20 54 68 65 20 64 65  usted..** The de
2cf50 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20  fault value for 
2cf60 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2cf70 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  mit is zero..**.
2cf80 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
2cf90 61 20 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f  a best effort to
2cfa0 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20   honor the soft 
2cfb0 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42  heap limit..** B
2cfc0 75 74 20 69 66 20 74 68 65 20 73 6f 66 74 20 68  ut if the soft h
2cfd0 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74  eap limit cannot
2cfe0 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65   be honored, exe
2cff0 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63  cution will.** c
2d000 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20  ontinue without 
2d010 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63  error or notific
2d020 61 74 69 6f 6e 2e 20 20 54 68 69 73 20 69 73 20  ation.  This is 
2d030 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73  why the limit is
2d040 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f  .** called a "so
2d050 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69  ft" limit.  It i
2d060 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e  s advisory only.
2d070 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
2d080 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2d090 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69  .5.0, this routi
2d0a0 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69  ne only constrai
2d0b0 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ned the memory.*
2d0c0 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61  * allocated by a
2d0d0 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d   single thread -
2d0e0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2d0f0 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20 72   in which this r
2d100 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20  outine.** runs. 
2d110 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20   Beginning with 
2d120 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2d130 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68  .5.0, the soft h
2d140 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20  eap limit is.** 
2d150 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74  applied to all t
2d160 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c 75  hreads. The valu
2d170 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 20  e specified for 
2d180 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2d190 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70  mit.** is an upp
2d1a0 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20  er bound on the 
2d1b0 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  total memory all
2d1c0 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20  ocation for all 
2d1d0 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76  threads. In.** v
2d1e0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65  ersion 3.5.0 the
2d1f0 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69  re is no mechani
2d200 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20  sm for limiting 
2d210 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20 66  the heap usage f
2d220 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c  or.** individual
2d230 20 74 68 72 65 61 64 73 2e 0a 2a 2a 0a 2a 2a 20   threads..**.** 
2d240 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a  Requirements:.**
2d250 20 5b 48 31 36 33 35 31 5d 20 5b 48 31 36 33 35   [H16351] [H1635
2d260 32 5d 20 5b 48 31 36 33 35 33 5d 20 5b 48 31 36  2] [H16353] [H16
2d270 33 35 34 5d 20 5b 48 31 36 33 35 35 5d 20 5b 48  354] [H16355] [H
2d280 31 36 33 35 38 5d 0a 2a 2f 0a 76 6f 69 64 20 73  16358].*/.void s
2d290 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
2d2a0 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a 0a 2f 2a  _limit(int);../*
2d2b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
2d2c0 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
2d2d0 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
2d2e0 20 41 20 54 61 62 6c 65 20 7b 48 31 32 38 35 30   A Table {H12850
2d2f0 7d 20 3c 53 36 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S60300>.**.**
2d300 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   This routine re
2d310 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61  turns metadata a
2d320 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20  bout a specific 
2d330 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63  column of a spec
2d340 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65  ific.** database
2d350 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c   table accessibl
2d360 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74  e using the [dat
2d370 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d380 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73  ] handle.** pass
2d390 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
2d3a0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
2d3b0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6c  t..**.** The col
2d3c0 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65  umn is identifie
2d3d0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c  d by the second,
2d3e0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
2d3f0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a  h parameters to.
2d400 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
2d410 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
2d420 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72  ameter is either
2d430 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2d440 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e   database.** (i.
2d450 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e. "main", "temp
2d460 22 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65 64  " or an attached
2d470 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74 61   database) conta
2d480 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69 66  ining the specif
2d490 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20  ied.** table or 
2d4a0 4e 55 4c 4c 2e 20 49 66 20 69 74 20 69 73 20 4e  NULL. If it is N
2d4b0 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74  ULL, then all at
2d4c0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
2d4d0 20 61 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a   are searched.**
2d4e0 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75   for the table u
2d4f0 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c  sing the same al
2d500 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62 79 20  gorithm used by 
2d510 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
2d520 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76  ine to.** resolv
2d530 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61  e unqualified ta
2d540 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a  ble references..
2d550 2a 2a 0a 2a 2a 20 54 68 65 20 74 68 69 72 64 20  **.** The third 
2d560 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
2d570 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
2d580 6e 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74  nction are the t
2d590 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a  able and column.
2d5a0 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  ** name of the d
2d5b0 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72  esired column, r
2d5c0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69  espectively. Nei
2d5d0 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61  ther of these pa
2d5e0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20  rameters.** may 
2d5f0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 4d  be NULL..**.** M
2d600 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72  etadata is retur
2d610 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74  ned by writing t
2d620 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63  o the memory loc
2d630 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73  ations passed as
2d640 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20   the 5th.** and 
2d650 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
2d660 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
2d670 6e 63 74 69 6f 6e 2e 20 41 6e 79 20 6f 66 20 74  nction. Any of t
2d680 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d  hese arguments m
2d690 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69  ay be.** NULL, i
2d6a0 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
2d6b0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65   corresponding e
2d6c0 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61  lement of metada
2d6d0 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  ta is omitted..*
2d6e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2d6f0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2d700 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2d710 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74  th> Parameter <t
2d720 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70  h> Output<br>Typ
2d730 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74  e <th>  Descript
2d740 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2d750 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 5th <td> cons
2d760 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74  t char* <td> Dat
2d770 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74  a type.** <tr><t
2d780 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 6th <td> cons
2d790 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d  t char* <td> Nam
2d7a0 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c  e of default col
2d7b0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a  lation sequence.
2d7c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20  ** <tr><td> 7th 
2d7d0 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
2d7e0 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
2d7f0 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e  lumn has a NOT N
2d800 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  ULL constraint.*
2d810 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c  * <tr><td> 8th <
2d820 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2d830 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2d840 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74  umn is part of t
2d850 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a  he PRIMARY KEY.*
2d860 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c  * <tr><td> 9th <
2d870 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2d880 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2d890 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52  umn is [AUTOINCR
2d8a0 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c  EMENT].** </tabl
2d8b0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2d8c0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 65  te>.**.** The me
2d8d0 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  mory pointed to 
2d8e0 62 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72  by the character
2d8f0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
2d900 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65  ed for the.** de
2d910 63 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61  claration type a
2d920 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  nd collation seq
2d930 75 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f  uence is valid o
2d940 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65  nly until the ne
2d950 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e  xt.** call to an
2d960 79 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e  y SQLite API fun
2d970 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ction..**.** If 
2d980 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61  the specified ta
2d990 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20  ble is actually 
2d9a0 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f  a view, an [erro
2d9b0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2d9c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ned..**.** If th
2d9d0 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75  e specified colu
2d9e0 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22  mn is "rowid", "
2d9f0 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f  oid" or "_rowid_
2da00 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54  " and an.** [INT
2da10 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
2da20 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65  ] column has bee
2da30 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  n explicitly dec
2da40 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20  lared, then the 
2da50 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65  output.** parame
2da60 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f 72  ters are set for
2da70 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20   the explicitly 
2da80 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e  declared column.
2da90 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a   If there is no.
2daa0 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  ** explicitly de
2dab0 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20  clared [INTEGER 
2dac0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c  PRIMARY KEY] col
2dad0 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  umn, then the ou
2dae0 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  tput.** paramete
2daf0 72 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f  rs are set as fo
2db00 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  llows:.**.** <pr
2db10 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74  e>.**     data t
2db20 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a  ype: "INTEGER".*
2db30 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20  *     collation 
2db40 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52  sequence: "BINAR
2db50 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75  Y".**     not nu
2db60 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69  ll: 0.**     pri
2db70 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20  mary key: 1.**  
2db80 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e     auto incremen
2db90 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 0a 2a  t: 0.** </pre>.*
2dba0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
2dbb0 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20  on may load one 
2dbc0 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20  or more schemas 
2dbd0 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69  from database fi
2dbe0 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72  les. If an.** er
2dbf0 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
2dc00 67 20 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20  g this process, 
2dc10 6f 72 20 69 66 20 74 68 65 20 72 65 71 75 65 73  or if the reques
2dc20 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c  ted table or col
2dc30 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  umn.** cannot be
2dc40 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f   found, an [erro
2dc50 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2dc60 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72  ned and an error
2dc70 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a   message left.**
2dc80 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   in the [databas
2dc90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
2dca0 6f 20 62 65 20 72 65 74 72 69 65 76 65 64 20 75  o be retrieved u
2dcb0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72  sing sqlite3_err
2dcc0 6d 73 67 28 29 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  msg())..**.** Th
2dcd0 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61  is API is only a
2dce0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2dcf0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2dd00 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2dd10 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2dd20 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2dd30 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2dd40 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
2dd50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
2dd60 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61  able_column_meta
2dd70 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20  data(.  sqlite3 
2dd80 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2dd90 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f      /* Connectio
2dda0 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  n handle */.  co
2ddb0 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
2ddc0 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74  e,        /* Dat
2ddd0 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55  abase name or NU
2dde0 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  LL */.  const ch
2ddf0 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20  ar *zTableName, 
2de00 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d      /* Table nam
2de10 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2de20 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20  r *zColumnName, 
2de30 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d     /* Column nam
2de40 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
2de50 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20  t **pzDataType, 
2de60 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65     /* OUTPUT: De
2de70 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65  clared data type
2de80 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
2de90 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20   **pzCollSeq,   
2dea0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c    /* OUTPUT: Col
2deb0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
2dec0 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  name */.  int *p
2ded0 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20  NotNull,        
2dee0 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
2def0 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c   True if NOT NUL
2df00 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69  L constraint exi
2df10 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50  sts */.  int *pP
2df20 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20  rimaryKey,      
2df30 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2df40 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70  True if column p
2df50 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69  art of PK */.  i
2df60 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20  nt *pAutoinc    
2df70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
2df80 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
2df90 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63  lumn is auto-inc
2dfa0 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a  rement */.);../*
2dfb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
2dfc0 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 20  ad An Extension 
2dfd0 7b 48 31 32 36 30 30 7d 20 3c 53 32 30 35 30 30  {H12600} <S20500
2dfe0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  >.**.** This int
2dff0 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20  erface loads an 
2e000 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
2e010 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68   library from th
2e020 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a  e named file..**
2e030 0a 2a 2a 20 7b 48 31 32 36 30 31 7d 20 54 68 65  .** {H12601} The
2e040 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
2e050 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66  tension() interf
2e060 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
2e070 6c 6f 61 64 20 61 6e 0a 2a 2a 20 20 20 20 20 20  load an.**      
2e080 20 20 20 20 53 51 4c 69 74 65 20 65 78 74 65 6e      SQLite exten
2e090 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e  sion library con
2e0a0 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69  tained in the fi
2e0b0 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  le zFile..**.** 
2e0c0 7b 48 31 32 36 30 32 7d 20 54 68 65 20 65 6e 74  {H12602} The ent
2e0d0 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f  ry point is zPro
2e0e0 63 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 33  c..**.** {H12603
2e0f0 7d 20 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30  } zProc may be 0
2e100 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
2e110 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2e120 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 20  entry point.**  
2e130 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 73          defaults
2e140 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74   to "sqlite3_ext
2e150 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a  ension_init"..**
2e160 0a 2a 2a 20 7b 48 31 32 36 30 34 7d 20 54 68 65  .** {H12604} The
2e170 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78   sqlite3_load_ex
2e180 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66  tension() interf
2e190 61 63 65 20 73 68 61 6c 6c 20 72 65 74 75 72 6e  ace shall return
2e1a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 53 51  .**          [SQ
2e1b0 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
2e1c0 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ess and [SQLITE_
2e1d0 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68  ERROR] if someth
2e1e0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
2e1f0 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 35 7d 20 49  **.** {H12605} I
2e200 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
2e210 73 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69  s and pzErrMsg i
2e220 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68  s not 0, then th
2e230 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 5b 73  e.**          [s
2e240 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2e250 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
2e260 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74  ce shall attempt
2e270 20 74 6f 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   to.**          
2e280 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77  fill *pzErrMsg w
2e290 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ith error messag
2e2a0 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69 6e  e text stored in
2e2b0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 20 20 20 20 20   memory.**      
2e2c0 20 20 20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f      obtained fro
2e2d0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2e2e0 63 28 29 5d 2e 20 7b 45 4e 44 7d 20 20 54 68 65  c()]. {END}  The
2e2f0 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
2e300 6e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 73 68  n.**          sh
2e310 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d  ould free this m
2e320 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67  emory by calling
2e330 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2e340 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 30 36  ]..**.** {H12606
2e350 7d 20 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  } Extension load
2e360 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62  ing must be enab
2e370 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 20 20 20  led using.**    
2e380 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 65        [sqlite3_e
2e390 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2e3a0 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f  sion()] prior to
2e3b0 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50   calling this AP
2e3c0 49 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6f  I,.**          o
2e3d0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
2e3e0 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e  r will be return
2e3f0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
2e400 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
2e410 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
2e420 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f  ,          /* Lo
2e430 61 64 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e  ad the extension
2e440 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62   into this datab
2e450 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a  ase connection *
2e460 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2e470 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d  zFile,    /* Nam
2e480 65 20 6f 66 20 74 68 65 20 73 68 61 72 65 64 20  e of the shared 
2e490 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69  library containi
2e4a0 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a  ng extension */.
2e4b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
2e4c0 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79  roc,    /* Entry
2e4d0 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64   point.  Derived
2e4e0 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30   from zFile if 0
2e4f0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
2e500 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50  rrMsg       /* P
2e510 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ut error message
2e520 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a   here if not 0 *
2e530 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2e540 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
2e550 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f  Disable Extensio
2e560 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 31 32 36 32  n Loading {H1262
2e570 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a 2a  0} <S20500>.**.*
2e580 2a 20 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f  * So as not to o
2e590 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f 6c  pen security hol
2e5a0 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c  es in older appl
2e5b0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72  ications that ar
2e5c0 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64 20  e.** unprepared 
2e5d0 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78 74  to deal with ext
2e5e0 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20  ension loading, 
2e5f0 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20 6f  and as a means o
2e600 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65  f disabling.** e
2e610 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
2e620 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
2e630 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53  g user-entered S
2e640 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  QL, the followin
2e650 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76  g API.** is prov
2e660 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68 65  ided to turn the
2e670 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
2e680 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68  xtension()] mech
2e690 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66  anism on and off
2e6a0 2e 0a 2a 2a 0a 2a 2a 20 45 78 74 65 6e 73 69 6f  ..**.** Extensio
2e6b0 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66  n loading is off
2e6c0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65   by default. See
2e6d0 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a   ticket #1863..*
2e6e0 2a 0a 2a 2a 20 7b 48 31 32 36 32 31 7d 20 43 61  *.** {H12621} Ca
2e6f0 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  ll the sqlite3_e
2e700 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2e710 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77  sion() routine w
2e720 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20  ith onoff==1.** 
2e730 20 20 20 20 20 20 20 20 20 74 6f 20 74 75 72 6e           to turn
2e740 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
2e750 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69  ng on and call i
2e760 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20  t with onoff==0 
2e770 74 6f 20 74 75 72 6e 0a 2a 2a 20 20 20 20 20 20  to turn.**      
2e780 20 20 20 20 69 74 20 62 61 63 6b 20 6f 66 66 20      it back off 
2e790 61 67 61 69 6e 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31  again..**.** {H1
2e7a0 32 36 32 32 7d 20 45 78 74 65 6e 73 69 6f 6e 20  2622} Extension 
2e7b0 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62  loading is off b
2e7c0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2f 0a 69 6e  y default..*/.in
2e7d0 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65  t sqlite3_enable
2e7e0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2e7f0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74  sqlite3 *db, int
2e800 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
2e810 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61  CAPI3REF: Automa
2e820 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20  tically Load An 
2e830 45 78 74 65 6e 73 69 6f 6e 73 20 7b 48 31 32 36  Extensions {H126
2e840 34 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a 0a  40} <S20500>.**.
2e850 2a 2a 20 54 68 69 73 20 41 50 49 20 63 61 6e 20  ** This API can 
2e860 62 65 20 69 6e 76 6f 6b 65 64 20 61 74 20 70 72  be invoked at pr
2e870 6f 67 72 61 6d 20 73 74 61 72 74 75 70 20 69 6e  ogram startup in
2e880 20 6f 72 64 65 72 20 74 6f 20 72 65 67 69 73 74   order to regist
2e890 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
2e8a0 65 20 73 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e  e statically lin
2e8b0 6b 65 64 20 65 78 74 65 6e 73 69 6f 6e 73 20 74  ked extensions t
2e8c0 68 61 74 20 77 69 6c 6c 20 62 65 20 61 76 61 69  hat will be avai
2e8d0 6c 61 62 6c 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20  lable.** to all 
2e8e0 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f  new [database co
2e8f0 6e 6e 65 63 74 69 6f 6e 73 5d 2e 20 7b 45 4e 44  nnections]. {END
2e900 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  }.**.** This rou
2e910 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70 6f  tine stores a po
2e920 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78 74  inter to the ext
2e930 65 6e 73 69 6f 6e 20 69 6e 20 61 6e 20 61 72 72  ension in an arr
2e940 61 79 20 74 68 61 74 20 69 73 0a 2a 2a 20 6f 62  ay that is.** ob
2e950 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2e960 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
2e970 20 49 66 20 79 6f 75 20 72 75 6e 20 61 20 6d 65   If you run a me
2e980 6d 6f 72 79 20 6c 65 61 6b 20 63 68 65 63 6b 65  mory leak checke
2e990 72 0a 2a 2a 20 6f 6e 20 79 6f 75 72 20 70 72 6f  r.** on your pro
2e9a0 67 72 61 6d 20 61 6e 64 20 69 74 20 72 65 70 6f  gram and it repo
2e9b0 72 74 73 20 61 20 6c 65 61 6b 20 62 65 63 61 75  rts a leak becau
2e9c0 73 65 20 6f 66 20 74 68 69 73 20 61 72 72 61 79  se of this array
2e9d0 2c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c  , invoke.** [sql
2e9e0 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
2e9f0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69  extension()] pri
2ea00 6f 72 20 74 6f 20 73 68 75 74 64 6f 77 6e 20 74  or to shutdown t
2ea10 6f 20 66 72 65 65 20 74 68 65 20 6d 65 6d 6f 72  o free the memor
2ea20 79 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 31  y..**.** {H12641
2ea30 7d 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  } This function 
2ea40 72 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 74  registers an ext
2ea50 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69  ension entry poi
2ea60 6e 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 20 20  nt that is.**   
2ea70 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69 63         automatic
2ea80 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68 65  ally invoked whe
2ea90 6e 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61 74  never a new [dat
2eaa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2eab0 5d 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 73  ].**          is
2eac0 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20 5b 73   opened using [s
2ead0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2eae0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2eaf0 29 5d 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  )],.**          
2eb00 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
2eb10 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 7b 48  _v2()]..**.** {H
2eb20 31 32 36 34 32 7d 20 44 75 70 6c 69 63 61 74 65  12642} Duplicate
2eb30 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72 65 20   extensions are 
2eb40 64 65 74 65 63 74 65 64 20 73 6f 20 63 61 6c 6c  detected so call
2eb50 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
2eb60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6d 75 6c  .**          mul
2eb70 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
2eb80 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73   the same extens
2eb90 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  ion is harmless.
2eba0 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 33 7d 20  .**.** {H12643} 
2ebb0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  This routine sto
2ebc0 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  res a pointer to
2ebd0 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
2ebe0 6e 20 61 6e 20 61 72 72 61 79 0a 2a 2a 20 20 20  n an array.**   
2ebf0 20 20 20 20 20 20 20 74 68 61 74 20 69 73 20 6f         that is o
2ec00 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2ec10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
2ec20 0a 2a 2a 0a 2a 2a 20 7b 48 31 32 36 34 34 7d 20  .**.** {H12644} 
2ec30 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73  Automatic extens
2ec40 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73  ions apply acros
2ec50 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a  s all threads..*
2ec60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75  /.int sqlite3_au
2ec70 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
2ec80 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29  d (*xEntryPoint)
2ec90 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void));../*.** 
2eca0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
2ecb0 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73  Automatic Extens
2ecc0 69 6f 6e 20 4c 6f 61 64 69 6e 67 20 7b 48 31 32  ion Loading {H12
2ecd0 36 36 30 7d 20 3c 53 32 30 35 30 30 3e 0a 2a 2a  660} <S20500>.**
2ece0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
2ecf0 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70  n disables all p
2ed00 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74  reviously regist
2ed10 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a  ered automatic.*
2ed20 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20 7b 45  * extensions. {E
2ed30 4e 44 7d 20 20 49 74 20 75 6e 64 6f 65 73 20 74  ND}  It undoes t
2ed40 68 65 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c  he effect of all
2ed50 20 70 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74   prior.** [sqlit
2ed60 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
2ed70 6e 28 29 5d 20 63 61 6c 6c 73 2e 0a 2a 2a 0a 2a  n()] calls..**.*
2ed80 2a 20 7b 48 31 32 36 36 31 7d 20 54 68 69 73 20  * {H12661} This 
2ed90 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
2eda0 73 20 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79  s all previously
2edb0 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 20   registered.**  
2edc0 20 20 20 20 20 20 20 20 61 75 74 6f 6d 61 74 69          automati
2edd0 63 20 65 78 74 65 6e 73 69 6f 6e 73 2e 0a 2a 2a  c extensions..**
2ede0 0a 2a 2a 20 7b 48 31 32 36 36 32 7d 20 54 68 69  .** {H12662} Thi
2edf0 73 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62  s function disab
2ee00 6c 65 73 20 61 75 74 6f 6d 61 74 69 63 20 65 78  les automatic ex
2ee10 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20  tensions in all 
2ee20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64  threads..*/.void
2ee30 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61   sqlite3_reset_a
2ee40 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f  uto_extension(vo
2ee50 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20  id);../*.****** 
2ee60 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73  EXPERIMENTAL - s
2ee70 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
2ee80 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20   without notice 
2ee90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a  **************.*
2eea0 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61  *.** The interfa
2eeb0 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61  ce to the virtua
2eec0 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
2eed0 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  m is currently c
2eee0 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
2eef0 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
2ef00 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
2ef10 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
2ef20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
2ef30 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
2ef40 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
2ef50 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
2ef60 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
2ef70 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
2ef80 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
2ef90 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
2efa0 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65  m stabilizes, we
2efb0 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
2efc0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
2efd0 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
2efe0 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
2eff0 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
2f000 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a  omment..*/../*.*
2f010 2a 20 53 74 72 75 63 74 75 72 65 73 20 75 73 65  * Structures use
2f020 64 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c  d by the virtual
2f030 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65   table interface
2f040 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2f050 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  ct sqlite3_vtab 
2f060 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79  sqlite3_vtab;.ty
2f070 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2f080 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20  ite3_index_info 
2f090 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
2f0a0 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  fo;.typedef stru
2f0b0 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  ct sqlite3_vtab_
2f0c0 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76  cursor sqlite3_v
2f0d0 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65  tab_cursor;.type
2f0e0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2f0f0 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65  e3_module sqlite
2f100 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a  3_module;../*.**
2f110 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75   CAPI3REF: Virtu
2f120 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 20  al Table Object 
2f130 7b 48 31 38 30 30 30 7d 20 3c 53 32 30 34 30 30  {H18000} <S20400
2f140 3e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  >.** KEYWORDS: s
2f150 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76  qlite3_module {v
2f160 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
2f170 75 6c 65 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45  ule}.** EXPERIME
2f180 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  NTAL.**.** This 
2f190 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74  structure, somet
2f1a0 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 61 20  imes called a a 
2f1b0 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  "virtual table m
2f1c0 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69  odule", .** defi
2f1d0 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nes the implemen
2f1e0 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72  tation of a [vir
2f1f0 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a  tual tables].  .
2f200 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
2f210 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c  e consists mostl
2f220 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72  y of methods for
2f230 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a   the module..**.
2f240 2a 2a 20 41 20 76 69 72 74 75 61 6c 20 74 61 62  ** A virtual tab
2f250 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65  le module is cre
2f260 61 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20  ated by filling 
2f270 69 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a  in a persistent.
2f280 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
2f290 68 69 73 20 73 74 72 75 63 74 75 72 65 20 61 6e  his structure an
2f2a0 64 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e  d passing a poin
2f2b0 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74  ter to that inst
2f2c0 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ance.** to [sqli
2f2d0 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
2f2e0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
2f2f0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
2f300 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 72 65 67  2()]..** The reg
2f310 69 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e  istration remain
2f320 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74  s valid until it
2f330 20 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20   is replaced by 
2f340 61 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d  a different.** m
2f350 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74  odule or until t
2f360 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2f370 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e  nection] closes.
2f380 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a    The content.**
2f390 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
2f3a0 72 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e  re must not chan
2f3b0 67 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72  ge while it is r
2f3c0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a  egistered with.*
2f3d0 2a 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  * any database c
2f3e0 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74  onnection..*/.st
2f3f0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
2f400 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ule {.  int iVer
2f410 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
2f420 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c  reate)(sqlite3*,
2f430 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
2f440 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
2f450 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
2f460 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
2f470 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
2f480 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
2f490 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
2f4a0 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73  nt (*xConnect)(s
2f4b0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
2f4c0 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
2f4d0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
2f4e0 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
2f4f0 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
2f500 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
2f510 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
2f520 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65  **);.  int (*xBe
2f530 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33  stIndex)(sqlite3
2f540 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
2f550 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
2f560 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73  *);.  int (*xDis
2f570 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  connect)(sqlite3
2f580 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
2f590 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29   int (*xDestroy)
2f5a0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2f5b0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2f5c0 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  Open)(sqlite3_vt
2f5d0 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
2f5e0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a  e3_vtab_cursor *
2f5f0 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e  *ppCursor);.  in
2f600 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
2f610 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
2f620 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74  );.  int (*xFilt
2f630 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  er)(sqlite3_vtab
2f640 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64  _cursor*, int id
2f650 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72  xNum, const char
2f660 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20   *idxStr,.      
2f670 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
2f680 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  gc, sqlite3_valu
2f690 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74  e **argv);.  int
2f6a0 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65   (*xNext)(sqlite
2f6b0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
2f6c0 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73  .  int (*xEof)(s
2f6d0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
2f6e0 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  or*);.  int (*xC
2f6f0 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76  olumn)(sqlite3_v
2f700 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
2f710 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2f720 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  nt);.  int (*xRo
2f730 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61  wid)(sqlite3_vta
2f740 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74  b_cursor*, sqlit
2f750 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64  e3_int64 *pRowid
2f760 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61  );.  int (*xUpda
2f770 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  te)(sqlite3_vtab
2f780 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33   *, int, sqlite3
2f790 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74  _value **, sqlit
2f7a0 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69  e3_int64 *);.  i
2f7b0 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c  nt (*xBegin)(sql
2f7c0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
2f7d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
2f7e0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2f7f0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
2f800 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33  xCommit)(sqlite3
2f810 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
2f820 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b   int (*xRollback
2f830 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
2f840 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
2f850 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73  xFindFunction)(s
2f860 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
2f870 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f  ab, int nArg, co
2f880 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
2f890 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2f8a0 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a          void (**
2f8b0 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  pxFunc)(sqlite3_
2f8c0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
2f8d0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
2f8e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f8f0 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41        void **ppA
2f900 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  rg);.  int (*xRe
2f910 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74  name)(sqlite3_vt
2f920 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74  ab *pVtab, const
2f930 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b   char *zNew);.};
2f940 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f950 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
2f960 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61  Indexing Informa
2f970 74 69 6f 6e 20 7b 48 31 38 31 30 30 7d 20 3c 53  tion {H18100} <S
2f980 32 30 34 30 30 3e 0a 2a 2a 20 4b 45 59 57 4f 52  20400>.** KEYWOR
2f990 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  DS: sqlite3_inde
2f9a0 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58 50 45 52 49  x_info.** EXPERI
2f9b0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
2f9c0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2f9d0 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61 6e  nfo structure an
2f9e0 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74 75  d its substructu
2f9f0 72 65 73 20 69 73 20 75 73 65 64 20 74 6f 0a 2a  res is used to.*
2fa00 2a 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69  * pass informati
2fa10 6f 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65  on into and rece
2fa20 69 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72  ive the reply fr
2fa30 6f 6d 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64  om the [xBestInd
2fa40 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66  ex].** method of
2fa50 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
2fa60 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20  e module].  The 
2fa70 66 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49  fields under **I
2fa80 6e 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a  nputs** are the.
2fa90 2a 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65  ** inputs to xBe
2faa0 73 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20  stIndex and are 
2fab0 72 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73  read-only.  xBes
2fac0 74 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69  tIndex inserts i
2fad0 74 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ts.** results in
2fae0 74 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73  to the **Outputs
2faf0 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a  ** fields..**.**
2fb00 20 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74   The aConstraint
2fb10 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73  [] array records
2fb20 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
2fb30 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65  nstraints of the
2fb40 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72   form:.**.** <pr
2fb50 65 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72  e>column OP expr
2fb60 3c 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65  </pre>.**.** whe
2fb70 72 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b  re OP is =, &lt;
2fb80 2c 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f  , &lt;=, &gt;, o
2fb90 72 20 26 67 74 3b 3d 2e 20 20 54 68 65 20 70 61  r &gt;=.  The pa
2fba0 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f  rticular operato
2fbb0 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69  r is.** stored i
2fbc0 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e  n aConstraint[].
2fbd0 6f 70 2e 20 20 54 68 65 20 69 6e 64 65 78 20 6f  op.  The index o
2fbe0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
2fbf0 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43 6f  stored in.** aCo
2fc00 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75  nstraint[].iColu
2fc10 6d 6e 2e 20 20 61 43 6f 6e 73 74 72 61 69 6e 74  mn.  aConstraint
2fc20 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55  [].usable is TRU
2fc30 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72  E if the.** expr
2fc40 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61   on the right-ha
2fc50 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65  nd side can be e
2fc60 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68  valuated (and th
2fc70 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  us the constrain
2fc80 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20  t.** is usable) 
2fc90 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20  and false if it 
2fca0 63 61 6e 6e 6f 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  cannot..**.** Th
2fcb0 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f  e optimizer auto
2fcc0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74  matically invert
2fcd0 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66  s terms of the f
2fce0 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c  orm "expr OP col
2fcf0 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65  umn".** and make
2fd00 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69  s other simplifi
2fd10 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57  cations to the W
2fd20 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61  HERE clause in a
2fd30 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20  n attempt to.** 
2fd40 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52  get as many WHER
2fd50 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69  E clause terms i
2fd60 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f  nto the form sho
2fd70 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73  wn above as poss
2fd80 69 62 6c 65 2e 0a 2a 2a 20 54 68 65 20 61 43 6f  ible..** The aCo
2fd90 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
2fda0 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48   only reports WH
2fdb0 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73  ERE clause terms
2fdc0 20 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a   in the correct.
2fdd0 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66  ** form that ref
2fde0 65 72 20 74 6f 20 74 68 65 20 70 61 72 74 69 63  er to the partic
2fdf0 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62  ular virtual tab
2fe00 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64  le being queried
2fe10 2e 0a 2a 2a 0a 2a 2a 20 49 6e 66 6f 72 6d 61 74  ..**.** Informat
2fe20 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52  ion about the OR
2fe30 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73  DER BY clause is
2fe40 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65   stored in aOrde
2fe50 72 42 79 5b 5d 2e 0a 2a 2a 20 45 61 63 68 20 74  rBy[]..** Each t
2fe60 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20  erm of aOrderBy 
2fe70 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e  records a column
2fe80 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59   of the ORDER BY
2fe90 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54   clause..**.** T
2fea0 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20  he [xBestIndex] 
2feb0 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c  method must fill
2fec0 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
2fed0 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61  e[] with informa
2fee0 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68  tion.** about wh
2fef0 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  at parameters to
2ff00 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72   pass to xFilter
2ff10 2e 20 20 49 66 20 61 72 67 76 49 6e 64 65 78 3e  .  If argvIndex>
2ff20 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69  0 then.** the ri
2ff30 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  ght-hand side of
2ff40 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2ff50 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ng aConstraint[]
2ff60 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a   is evaluated.**
2ff70 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65   and becomes the
2ff80 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e   argvIndex-th en
2ff90 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 49 66  try in argv.  If
2ffa0 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
2ffb0 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74  e[].omit.** is t
2ffc0 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f  rue, then the co
2ffd0 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73 75  nstraint is assu
2ffe0 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20  med to be fully 
2fff0 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a  handled by the.*
30000 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * virtual table 
30010 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b  and is not check
30020 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69  ed again by SQLi
30030 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 64  te..**.** The id
30040 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20  xNum and idxPtr 
30050 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72  values are recor
30060 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69  ded and passed i
30070 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c  nto the.** [xFil
30080 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20  ter] method..** 
30090 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
300a0 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65   is used to free
300b0 20 69 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f   idxPtr if and o
300c0 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e 65 65 64 54  nly iff.** needT
300d0 6f 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74  oFreeIdxPtr is t
300e0 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  rue..**.** The o
300f0 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d  rderByConsumed m
30100 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74  eans that output
30110 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f   from [xFilter]/
30120 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63  [xNext] will occ
30130 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72  ur in.** the cor
30140 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61  rect order to sa
30150 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20  tisfy the ORDER 
30160 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61  BY clause so tha
30170 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a  t no separate.**
30180 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73   sorting step is
30190 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
301a0 20 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f   The estimatedCo
301b0 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65  st value is an e
301c0 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63  stimate of the c
301d0 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65  ost of doing the
301e0 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c  .** particular l
301f0 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73  ookup.  A full s
30200 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77  can of a table w
30210 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68  ith N entries sh
30220 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63  ould have.** a c
30230 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e  ost of N.  A bin
30240 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20  ary search of a 
30250 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69  table of N entri
30260 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61  es should have a
30270 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72  .** cost of appr
30280 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29  oximately log(N)
30290 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
302a0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b  te3_index_info {
302b0 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a  .  /* Inputs */.
302c0 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e    int nConstrain
302d0 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t;           /* 
302e0 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65  Number of entrie
302f0 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  s in aConstraint
30300 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
30310 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
30320 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74  raint {.     int
30330 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
30340 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
30350 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69   on left-hand si
30360 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74  de of constraint
30370 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
30380 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20  d char op;      
30390 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74     /* Constraint
303a0 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20   operator */.   
303b0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
303c0 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54  usable;     /* T
303d0 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73  rue if this cons
303e0 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65  traint is usable
303f0 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65   */.     int iTe
30400 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20  rmOffset;       
30410 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72     /* Used inter
30420 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64  nally - xBestInd
30430 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65  ex should ignore
30440 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72   */.  } *aConstr
30450 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20  aint;           
30460 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45   /* Table of WHE
30470 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
30480 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  aints */.  int n
30490 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20  OrderBy;        
304a0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
304b0 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20  of terms in the 
304c0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
304d0 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
304e0 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62  te3_index_orderb
304f0 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  y {.     int iCo
30500 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
30510 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d     /* Column num
30520 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  ber */.     unsi
30530 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20  gned char desc; 
30540 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f        /* True fo
30550 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66  r DESC.  False f
30560 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a  or ASC. */.  } *
30570 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  aOrderBy;       
30580 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f          /* The O
30590 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
305a0 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a  /.  /* Outputs *
305b0 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
305c0 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
305d0 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20  int_usage {.    
305e0 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20  int argvIndex;  
305f0 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e           /* if >
30600 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  0, constraint is
30610 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f   part of argv to
30620 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20   xFilter */.    
30630 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d  unsigned char om
30640 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e  it;      /* Do n
30650 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66  ot code a test f
30660 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  or this constrai
30670 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73  nt */.  } *aCons
30680 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69  traintUsage;.  i
30690 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20  nt idxNum;      
306a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
306b0 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e  ber used to iden
306c0 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a  tify the index *
306d0 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72  /.  char *idxStr
306e0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
306f0 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62  * String, possib
30700 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
30710 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20   sqlite3_malloc 
30720 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46  */.  int needToF
30730 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20  reeIdxStr;      
30740 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75  /* Free idxStr u
30750 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  sing sqlite3_fre
30760 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20  e() if true */. 
30770 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73   int orderByCons
30780 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54  umed;       /* T
30790 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73  rue if output is
307a0 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64   already ordered
307b0 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74   */.  double est
307c0 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20  imatedCost;     
307d0 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f   /* Estimated co
307e0 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  st of using this
307f0 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 23 64 65   index */.};.#de
30800 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
30810 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20  X_CONSTRAINT_EQ 
30820 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
30830 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
30840 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65  AINT_GT    4.#de
30850 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
30860 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20  X_CONSTRAINT_LE 
30870 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
30880 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
30890 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64  AINT_LT    16.#d
308a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
308b0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45  EX_CONSTRAINT_GE
308c0 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53      32.#define S
308d0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
308e0 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a  TRAINT_MATCH 64.
308f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30900 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74   Register A Virt
30910 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d  ual Table Implem
30920 65 6e 74 61 74 69 6f 6e 20 7b 48 31 38 32 30 30  entation {H18200
30930 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 45 58  } <S20400>.** EX
30940 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
30950 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   This routine is
30960 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74 65   used to registe
30970 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c  r a new [virtual
30980 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e   table module] n
30990 61 6d 65 2e 0a 2a 2a 20 4d 6f 64 75 6c 65 20 6e  ame..** Module n
309a0 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72 65 67  ames must be reg
309b0 69 73 74 65 72 65 64 20 62 65 66 6f 72 65 0a 2a  istered before.*
309c0 2a 20 63 72 65 61 74 69 6e 67 20 61 20 6e 65 77  * creating a new
309d0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
309e0 20 75 73 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c   using the modul
309f0 65 2c 20 6f 72 20 62 65 66 6f 72 65 20 75 73 69  e, or before usi
30a00 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78 69 73 74  ng a.** preexist
30a10 69 6e 67 20 5b 76 69 72 74 75 61 6c 20 74 61 62  ing [virtual tab
30a20 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  le] for the modu
30a30 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 6f  le..**.** The mo
30a40 64 75 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67  dule name is reg
30a50 69 73 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b  istered on the [
30a60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30a70 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a  ion] specified.*
30a80 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  * by the first p
30a90 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6e  arameter.  The n
30aa0 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  ame of the modul
30ab0 65 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68  e is given by th
30ac0 65 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  e .** second par
30ad0 61 6d 65 74 65 72 2e 20 20 54 68 65 20 74 68 69  ameter.  The thi
30ae0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
30af0 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
30b00 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
30b10 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  on of the [virtu
30b20 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
30b30 2e 20 20 20 54 68 65 20 66 6f 75 72 74 68 0a 2a  .   The fourth.*
30b40 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  * parameter is a
30b50 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65  n arbitrary clie
30b60 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  nt data pointer 
30b70 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74  that is passed t
30b80 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74  hrough.** into t
30b90 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64  he [xCreate] and
30ba0 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68   [xConnect] meth
30bb0 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75  ods of the virtu
30bc0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a  al table module.
30bd0 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69  ** when a new vi
30be0 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62  rtual table is b
30bf0 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20  e being created 
30c00 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64  or reinitialized
30c10 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
30c20 65 72 66 61 63 65 20 68 61 73 20 65 78 61 63 74  erface has exact
30c30 6c 79 20 74 68 65 20 73 61 6d 65 20 65 66 66 65  ly the same effe
30c40 63 74 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  ct as calling.**
30c50 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30c60 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 20 77 69  _module_v2()] wi
30c70 74 68 20 61 20 4e 55 4c 4c 20 63 6c 69 65 6e 74  th a NULL client
30c80 20 64 61 74 61 20 64 65 73 74 72 75 63 74 6f 72   data destructor
30c90 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ..*/.SQLITE_EXPE
30ca0 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c  RIMENTAL int sql
30cb0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
30cc0 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
30cd0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
30ce0 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
30cf0 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
30d00 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
30d10 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
30d20 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
30d30 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
30d40 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
30d50 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
30d60 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  ,   /* Methods f
30d70 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
30d80 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74  .  void *pClient
30d90 44 61 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a  Data          /*
30da0 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
30db0 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
30dc0 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t */.);../*.** C
30dd0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
30de0 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  r A Virtual Tabl
30df0 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e Implementation
30e00 20 7b 48 31 38 32 31 30 7d 20 3c 53 32 30 34 30   {H18210} <S2040
30e10 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
30e20 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  AL.**.** This ro
30e30 75 74 69 6e 65 20 69 73 20 69 64 65 6e 74 69 63  utine is identic
30e40 61 6c 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  al to the [sqlit
30e50 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
30e60 28 29 5d 20 6d 65 74 68 6f 64 2c 0a 2a 2a 20 65  ()] method,.** e
30e70 78 63 65 70 74 20 74 68 61 74 20 69 74 20 68 61  xcept that it ha
30e80 73 20 61 6e 20 65 78 74 72 61 20 70 61 72 61 6d  s an extra param
30e90 65 74 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  eter to specify 
30ea0 0a 2a 2a 20 61 20 64 65 73 74 72 75 63 74 6f 72  .** a destructor
30eb0 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68   function for th
30ec0 65 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f  e client data po
30ed0 69 6e 74 65 72 2e 20 20 53 51 4c 69 74 65 20 77  inter.  SQLite w
30ee0 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ill.** invoke th
30ef0 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
30f00 63 74 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20  ction (if it is 
30f10 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53  not NULL) when S
30f20 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67  QLite.** no long
30f30 65 72 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c  er needs the pCl
30f40 69 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72  ientData pointer
30f50 2e 20 20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  .  .*/.SQLITE_EX
30f60 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73  PERIMENTAL int s
30f70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
30f80 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  dule_v2(.  sqlit
30f90 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
30fa0 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
30fb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
30fc0 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
30fd0 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
30fe0 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
30ff0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
31000 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
31010 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
31020 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68  le *p,   /* Meth
31030 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
31040 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43  le */.  void *pC
31050 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20 20  lientData,      
31060 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
31070 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
31080 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64  onnect */.  void
31090 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
310a0 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65  *)     /* Module
310b0 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
310c0 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  tion */.);../*.*
310d0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
310e0 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e  ual Table Instan
310f0 63 65 20 4f 62 6a 65 63 74 20 7b 48 31 38 30 31  ce Object {H1801
31100 30 7d 20 3c 53 32 30 34 30 30 3e 0a 2a 2a 20 4b  0} <S20400>.** K
31110 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
31120 5f 76 74 61 62 0a 2a 2a 20 45 58 50 45 52 49 4d  _vtab.** EXPERIM
31130 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72  ENTAL.**.** Ever
31140 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  y [virtual table
31150 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65   module] impleme
31160 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73  ntation uses a s
31170 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68  ubclass.** of th
31180 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75  e following stru
31190 63 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62  cture to describ
311a0 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69  e a particular i
311b0 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68  nstance.** of th
311c0 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e [virtual table
311d0 5d 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73  ].  Each subclas
311e0 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69  s will.** be tai
311f0 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65  lored to the spe
31200 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74  cific needs of t
31210 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  he module implem
31220 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  entation..** The
31230 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73   purpose of this
31240 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74   superclass is t
31250 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e  o define certain
31260 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65   fields that are
31270 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  .** common to al
31280 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  l module impleme
31290 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  ntations..**.** 
312a0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d  Virtual tables m
312b0 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61  ethods can set a
312c0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
312d0 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a  by assigning a.*
312e0 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  * string obtaine
312f0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
31300 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45  mprintf()] to zE
31310 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68  rrMsg.  The meth
31320 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b  od should.** tak
31330 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79 20  e care that any 
31340 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20  prior string is 
31350 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20  freed by a call 
31360 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
31370 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ()].** prior to 
31380 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20  assigning a new 
31390 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73  string to zErrMs
313a0 67 2e 20 20 41 66 74 65 72 20 74 68 65 20 65 72  g.  After the er
313b0 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69  ror message.** i
313c0 73 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74  s delivered up t
313d0 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70  o the client app
313e0 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74  lication, the st
313f0 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74  ring will be aut
31400 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72  omatically.** fr
31410 65 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66  eed by sqlite3_f
31420 72 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45  ree() and the zE
31430 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c  rrMsg field will
31440 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73   be zeroed..*/.s
31450 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
31460 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c  ab {.  const sql
31470 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f  ite3_module *pMo
31480 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f  dule;  /* The mo
31490 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69  dule for this vi
314a0 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20  rtual table */. 
314b0 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20   int nRef;      
314c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
314d0 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53   /* NO LONGER US
314e0 45 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45  ED */.  char *zE
314f0 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20  rrMsg;          
31500 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
31510 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71   message from sq
31520 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20  lite3_mprintf() 
31530 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
31540 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
31550 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
31560 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
31570 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
31580 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31590 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
315a0 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 20 20 7b  Cursor Object  {
315b0 48 31 38 30 32 30 7d 20 3c 53 32 30 34 30 30 3e  H18020} <S20400>
315c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
315d0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
315e0 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r {virtual table
315f0 20 63 75 72 73 6f 72 7d 0a 2a 2a 20 45 58 50 45   cursor}.** EXPE
31600 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45  RIMENTAL.**.** E
31610 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61  very [virtual ta
31620 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c  ble module] impl
31630 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20  ementation uses 
31640 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68  a subclass of th
31650 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73  e.** following s
31660 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73 63  tructure to desc
31670 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61  ribe cursors tha
31680 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65  t point into the
31690 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
316a0 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73 65 64  le] and are used
316b0 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f  .** to loop thro
316c0 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20  ugh the virtual 
316d0 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20  table.  Cursors 
316e0 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e  are created usin
316f0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
31700 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c  3_module.xOpen |
31710 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f   xOpen] method o
31720 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64  f the module and
31730 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 0a 2a   are destroyed.*
31740 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  * by the [sqlite
31750 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20  3_module.xClose 
31760 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64  | xClose] method
31770 2e 20 20 43 75 73 73 6f 72 73 20 61 72 65 20 75  .  Cussors are u
31780 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78  sed.** by the [x
31790 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d  Filter], [xNext]
317a0 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75  , [xEof], [xColu
317b0 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64  mn], and [xRowid
317c0 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20  ] methods.** of 
317d0 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63  the module.  Eac
317e0 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  h module impleme
317f0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66  ntation will def
31800 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65  ine.** the conte
31810 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73  nt of a cursor s
31820 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74  tructure to suit
31830 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a   its own needs..
31840 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72  **.** This super
31850 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20  class exists in 
31860 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20  order to define 
31870 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75  fields of the cu
31880 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65  rsor that.** are
31890 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69   common to all i
318a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
318b0 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
318c0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a  3_vtab_cursor {.
318d0 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a    sqlite3_vtab *
318e0 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56  pVtab;      /* V
318f0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20  irtual table of 
31900 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20  this cursor */. 
31910 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
31920 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
31930 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79  s will typically
31940 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
31950 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  fields */.};../*
31960 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
31970 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d 61  clare The Schema
31980 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54 61   Of A Virtual Ta
31990 62 6c 65 20 7b 48 31 38 32 38 30 7d 20 3c 53 32  ble {H18280} <S2
319a0 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d  0400>.** EXPERIM
319b0 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ENTAL.**.** The 
319c0 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78  [xCreate] and [x
319d0 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73  Connect] methods
319e0 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61   of a.** [virtua
319f0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
31a00 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66  call this interf
31a10 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72  ace.** to declar
31a20 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68  e the format (th
31a30 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61  e names and data
31a40 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  types of the col
31a50 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20  umns) of.** the 
31a60 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74  virtual tables t
31a70 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a  hey implement..*
31a80 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
31a90 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65  ENTAL int sqlite
31aa0 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73  3_declare_vtab(s
31ab0 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
31ac0 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a  har *zSQL);../*.
31ad0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65  ** CAPI3REF: Ove
31ae0 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e  rload A Function
31af0 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54   For A Virtual T
31b00 61 62 6c 65 20 7b 48 31 38 33 30 30 7d 20 3c 53  able {H18300} <S
31b10 32 30 34 30 30 3e 0a 2a 2a 20 45 58 50 45 52 49  20400>.** EXPERI
31b20 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 56 69 72  MENTAL.**.** Vir
31b30 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20  tual tables can 
31b40 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74  provide alternat
31b50 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ive implementati
31b60 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ons of functions
31b70 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78  .** using the [x
31b80 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65  FindFunction] me
31b90 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72  thod of the [vir
31ba0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
31bb0 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f  e].  .** But glo
31bc0 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  bal versions of 
31bd0 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a  those functions.
31be0 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e  ** must exist in
31bf0 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65   order to be ove
31c00 72 6c 6f 61 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  rloaded..**.** T
31c10 68 69 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75  his API makes su
31c20 72 65 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73  re a global vers
31c30 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f  ion of a functio
31c40 6e 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  n with a particu
31c50 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20  lar.** name and 
31c60 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65  number of parame
31c70 74 65 72 73 20 65 78 69 73 74 73 2e 20 20 49 66  ters exists.  If
31c80 20 6e 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f   no such functio
31c90 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f  n exists.** befo
31ca0 72 65 20 74 68 69 73 20 41 50 49 20 69 73 20 63  re this API is c
31cb0 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e  alled, a new fun
31cc0 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
31cd0 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
31ce0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20  ation.** of the 
31cf0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77  new function alw
31d00 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78  ays causes an ex
31d10 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  ception to be th
31d20 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65  rown.  So.** the
31d30 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73   new function is
31d40 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e   not good for an
31d50 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66  ything by itself
31d60 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70  .  Its only.** p
31d70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20  urpose is to be 
31d80 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75  a placeholder fu
31d90 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20  nction that can 
31da0 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a  be overloaded.**
31db0 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74   by a [virtual t
31dc0 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  able]..*/.SQLITE
31dd0 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e  _EXPERIMENTAL in
31de0 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f  t sqlite3_overlo
31df0 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69  ad_function(sqli
31e00 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  te3*, const char
31e10 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74   *zFuncName, int
31e20 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54   nArg);../*.** T
31e30 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
31e40 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
31e50 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69  e mechanism defi
31e60 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20  ned above (back 
31e70 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65  up.** to a comme
31e80 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69  nt remarkably si
31e90 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e  milar to this on
31ea0 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  e) is currently 
31eb0 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f  considered.** to
31ec0 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   be experimental
31ed0 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
31ee0 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
31ef0 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61   incompatible wa
31f00 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69  ys..** If this i
31f10 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20  s a problem for 
31f20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20  you, do not use 
31f30 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74  the interface at
31f40 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a   this time..**.*
31f50 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75  * When the virtu
31f60 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
31f70 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77  sm stabilizes, w
31f80 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74  e will declare t
31f90 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  he.** interface 
31fa0 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69  fixed, support i
31fb0 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20  t indefinitely, 
31fc0 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20  and remove this 
31fd0 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a 2a  comment..**.****
31fe0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  ** EXPERIMENTAL 
31ff0 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  - subject to cha
32000 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74 69  nge without noti
32010 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ce *************
32020 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *.*/../*.** CAPI
32030 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20 54  3REF: A Handle T
32040 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20 7b  o An Open BLOB {
32050 48 31 37 38 30 30 7d 20 3c 53 33 30 32 33 30 3e  H17800} <S30230>
32060 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42  .** KEYWORDS: {B
32070 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f  LOB handle} {BLO
32080 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a  B handles}.**.**
32090 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
320a0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
320b0 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42  esents an open B
320c0 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20  LOB on which.** 
320d0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
320e0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
320f0 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62   BLOB I/O] can b
32100 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20  e performed..** 
32110 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20  Objects of this 
32120 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65 64  type are created
32130 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
32140 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64  b_open()].** and
32150 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
32160 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
32170 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71  e()]..** The [sq
32180 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
32190 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
321a0 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69 6e  blob_write()] in
321b0 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20  terfaces.** can 
321c0 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64 20  be used to read 
321d0 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20 73  or write small s
321e0 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74 68  ubsections of th
321f0 65 20 42 4c 4f 42 2e 0a 2a 2a 20 54 68 65 20 5b  e BLOB..** The [
32200 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
32210 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  es()] interface 
32220 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
32230 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20   of the BLOB in 
32240 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  bytes..*/.typede
32250 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
32260 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c  _blob sqlite3_bl
32270 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ob;../*.** CAPI3
32280 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42  REF: Open A BLOB
32290 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c   For Incremental
322a0 20 49 2f 4f 20 7b 48 31 37 38 31 30 7d 20 3c 53   I/O {H17810} <S
322b0 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  30230>.**.** Thi
322c0 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65  s interfaces ope
322d0 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ns a [BLOB handl
322e0 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74  e | handle] to t
322f0 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a  he BLOB located.
32300 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20  ** in row iRow, 
32310 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20  column zColumn, 
32320 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20  table zTable in 
32330 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a  database zDb;.**
32340 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   in other words,
32350 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74   the same BLOB t
32360 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c  hat would be sel
32370 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20  ected by:.**.** 
32380 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c  <pre>.**     SEL
32390 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d  ECT zColumn FROM
323a0 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52   zDb.zTable WHER
323b0 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77  E [rowid] = iRow
323c0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 20 7b 45 4e 44  ;.** </pre> {END
323d0 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 66  }.**.** If the f
323e0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69  lags parameter i
323f0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
32400 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65   the BLOB is ope
32410 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20  ned for read.** 
32420 61 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73  and write access
32430 2e 20 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c  . If it is zero,
32440 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65   the BLOB is ope
32450 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 63  ned for read acc
32460 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ess..**.** Note 
32470 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
32480 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68  e name is not th
32490 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20  e filename that 
324a0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
324b0 64 61 74 61 62 61 73 65 20 62 75 74 20 72 61 74  database but rat
324c0 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63  her the symbolic
324d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
324e0 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 69 73  abase that.** is
324f0 20 61 73 73 69 67 6e 65 64 20 77 68 65 6e 20 74   assigned when t
32500 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 63  he database is c
32510 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20 5b  onnected using [
32520 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 46 6f 72 20  ATTACH]..** For 
32530 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
32540 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  e file, the data
32550 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61  base name is "ma
32560 69 6e 22 2e 0a 2a 2a 20 46 6f 72 20 54 45 4d 50  in"..** For TEMP
32570 20 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74   tables, the dat
32580 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74  abase name is "t
32590 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73  emp"..**.** On s
325a0 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
325b0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OK] is returned 
325c0 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f  and the new [BLO
325d0 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69  B handle] is wri
325e0 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c  tten.** to *ppBl
325f0 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e  ob. Otherwise an
32600 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
32610 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70   returned and *p
32620 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20  pBlob is set.** 
32630 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69  to be a null poi
32640 6e 74 65 72 2e 0a 2a 2a 20 54 68 69 73 20 66 75  nter..** This fu
32650 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20  nction sets the 
32660 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32670 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65  tion] error code
32680 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20   and message.** 
32690 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b  accessible via [
326a0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
326b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
326c0 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65  errmsg()] and re
326d0 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  lated.** functio
326e0 6e 73 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ns.  Note that t
326f0 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61  he *ppBlob varia
32700 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e  ble is always in
32710 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a  itialized in a.*
32720 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73  * way that makes
32730 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f   it safe to invo
32740 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ke [sqlite3_blob
32750 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70  _close()] on *pp
32760 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65  Blob.** regardle
32770 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
32780 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  s or failure of 
32790 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  this routine..**
327a0 0a 2a 2a 20 49 66 20 74 68 65 20 72 6f 77 20 74  .** If the row t
327b0 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c  hat a BLOB handl
327c0 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d  e points to is m
327d0 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a  odified by an.**
327e0 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45   [UPDATE], [DELE
327f0 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43  TE], or by [ON C
32800 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66  ONFLICT] side-ef
32810 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68  fects.** then th
32820 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73  e BLOB handle is
32830 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70 69   marked as "expi
32840 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73  red"..** This is
32850 20 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c   true if any col
32860 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69  umn of the row i
32870 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20  s changed, even 
32880 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65  a column.** othe
32890 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74  r than the one t
328a0 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69  he BLOB handle i
328b0 73 20 6f 70 65 6e 20 6f 6e 2e 0a 2a 2a 20 43 61  s open on..** Ca
328c0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
328d0 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64  blob_read()] and
328e0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
328f0 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61  rite()] for.** a
32900 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61   expired BLOB ha
32910 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61  ndle fail with a
32920 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66  n return code of
32930 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
32940 0a 2a 2a 20 43 68 61 6e 67 65 73 20 77 72 69 74  .** Changes writ
32950 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20  ten into a BLOB 
32960 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f  prior to the BLO
32970 42 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e  B expiring are n
32980 6f 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 20 62  ot.** rollback b
32990 79 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e  y the expiration
329a0 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53   of the BLOB.  S
329b0 75 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  uch changes will
329c0 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63   eventually.** c
329d0 6f 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61  ommit if the tra
329e0 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75  nsaction continu
329f0 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
32a00 2e 0a 2a 2a 0a 2a 2a 20 55 73 65 20 74 68 65 20  ..**.** Use the 
32a10 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
32a20 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
32a30 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
32a40 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65  e size of.** the
32a50 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 54   opened blob.  T
32a60 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f  he size of a blo
32a70 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61  b may not be cha
32a80 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  nged by this.** 
32a90 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65 20  interface.  Use 
32aa0 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c  the [UPDATE] SQL
32ab0 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e   command to chan
32ac0 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  ge the size of a
32ad0 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20  .** blob..**.** 
32ae0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
32af0 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e  d_zeroblob()] an
32b00 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
32b10 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e  t_zeroblob()] in
32b20 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20  terfaces.** and 
32b30 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65  the built-in [ze
32b40 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63  roblob] SQL func
32b50 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
32b60 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a  , if desired,.**
32b70 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d   to create an em
32b80 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64  pty, zero-filled
32b90 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74   blob in which t
32ba0 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  o read or write 
32bb0 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e  using.** this in
32bc0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
32bd0 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72  o avoid a resour
32be0 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f  ce leak, every o
32bf0 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  pen [BLOB handle
32c00 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61  ] should eventua
32c10 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73  lly.** be releas
32c20 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
32c30 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
32c40 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  ose()]..**.** Re
32c50 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
32c60 48 31 37 38 31 33 5d 20 5b 48 31 37 38 31 34 5d  H17813] [H17814]
32c70 20 5b 48 31 37 38 31 36 5d 20 5b 48 31 37 38 31   [H17816] [H1781
32c80 39 5d 20 5b 48 31 37 38 32 31 5d 20 5b 48 31 37  9] [H17821] [H17
32c90 38 32 34 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  824].*/.int sqli
32ca0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20  te3_blob_open(. 
32cb0 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e   sqlite3*,.  con
32cc0 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20  st char *zDb,.  
32cd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62  const char *zTab
32ce0 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  le,.  const char
32cf0 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c   *zColumn,.  sql
32d00 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c  ite3_int64 iRow,
32d10 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20  .  int flags,.  
32d20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70  sqlite3_blob **p
32d30 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  pBlob.);../*.** 
32d40 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20  CAPI3REF: Close 
32d50 41 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20 7b 48  A BLOB Handle {H
32d60 31 37 38 33 30 7d 20 3c 53 33 30 32 33 30 3e 0a  17830} <S30230>.
32d70 2a 2a 0a 2a 2a 20 43 6c 6f 73 65 73 20 61 6e 20  **.** Closes an 
32d80 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
32d90 65 5d 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e  e]..**.** Closin
32da0 67 20 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63  g a BLOB shall c
32db0 61 75 73 65 20 74 68 65 20 63 75 72 72 65 6e 74  ause the current
32dc0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
32dd0 63 6f 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65  commit.** if the
32de0 72 65 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20  re are no other 
32df0 42 4c 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e  BLOBs, no pendin
32e00 67 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  g prepared state
32e10 6d 65 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a  ments, and the.*
32e20 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
32e30 63 74 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74  ction is in [aut
32e40 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a  ocommit mode]..*
32e50 2a 20 49 66 20 61 6e 79 20 77 72 69 74 65 73 20  * If any writes 
32e60 77 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65  were made to the
32e70 20 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68   BLOB, they migh
32e80 74 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63  t be held in cac
32e90 68 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20  he.** until the 
32ea0 63 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  close operation 
32eb0 69 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74  if they will fit
32ec0 2e 0a 2a 2a 0a 2a 2a 20 43 6c 6f 73 69 6e 67 20  ..**.** Closing 
32ed0 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66  the BLOB often f
32ee0 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67 65  orces the change
32ef0 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b  s.** out to disk
32f00 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49   and so if any I
32f10 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c  /O errors occur,
32f20 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c   they will likel
32f30 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68  y occur.** at th
32f40 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  e time when the 
32f50 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20  BLOB is closed. 
32f60 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74   Any errors that
32f70 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a   occur during.**
32f80 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70   closing are rep
32f90 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a  orted as a non-z
32fa0 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ero return value
32fb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 42 4c 4f 42  ..**.** The BLOB
32fc0 20 69 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e   is closed uncon
32fd0 64 69 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65  ditionally.  Eve
32fe0 6e 20 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e  n if this routin
32ff0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20  e returns.** an 
33000 65 72 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20  error code, the 
33010 42 4c 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c  BLOB is still cl
33020 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 43 61 6c 6c  osed..**.** Call
33030 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
33040 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69   with a null poi
33050 6e 74 65 72 20 28 77 68 69 63 68 20 61 73 20 77  nter (which as w
33060 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
33070 0a 2a 2a 20 62 79 20 66 61 69 6c 65 64 20 63 61  .** by failed ca
33080 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
33090 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20  lob_open()]) is 
330a0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
330b0 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d  ..**.** Requirem
330c0 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 33 33  ents:.** [H17833
330d0 5d 20 5b 48 31 37 38 33 36 5d 20 5b 48 31 37 38  ] [H17836] [H178
330e0 33 39 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  39].*/.int sqlit
330f0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71  e3_blob_close(sq
33100 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
33110 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33120 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20  Return The Size 
33130 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 20  Of An Open BLOB 
33140 7b 48 31 37 38 34 30 7d 20 3c 53 33 30 32 33 30  {H17840} <S30230
33150 3e 0a 2a 2a 0a 2a 2a 20 52 65 74 75 72 6e 73 20  >.**.** Returns 
33160 74 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65  the size in byte
33170 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63  s of the BLOB ac
33180 63 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65  cessible via the
33190 20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c   .** successfull
331a0 79 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68  y opened [BLOB h
331b0 61 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e  andle] in its on
331c0 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  ly argument.  Th
331d0 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c  e.** incremental
331e0 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e   blob I/O routin
331f0 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64  es can only read
33200 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20   or overwriting 
33210 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62  existing.** blob
33220 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63   content; they c
33230 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
33240 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e   size of a blob.
33250 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
33260 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
33270 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
33280 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
33290 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
332a0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
332b0 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
332c0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
332d0 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
332e0 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
332f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
33300 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
33310 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
33320 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
33330 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
33340 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
33350 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
33360 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
33370 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75 69  ior..**.** Requi
33380 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31 37  rements:.** [H17
33390 38 34 33 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  843].*/.int sqli
333a0 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73  te3_blob_bytes(s
333b0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
333c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
333d0 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20   Read Data From 
333e0 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
333f0 61 6c 6c 79 20 7b 48 31 37 38 35 30 7d 20 3c 53  ally {H17850} <S
33400 33 30 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  30230>.**.** Thi
33410 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
33420 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20  ed to read data 
33430 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  from an open [BL
33440 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20  OB handle] into 
33450 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70  a.** caller-supp
33460 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62  lied buffer. N b
33470 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
33480 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66   copied into buf
33490 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68  fer Z.** from th
334a0 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61  e open BLOB, sta
334b0 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20  rting at offset 
334c0 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 49  iOffset..**.** I
334d0 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74  f offset iOffset
334e0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20   is less than N 
334f0 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65  bytes from the e
33500 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a  nd of the BLOB,.
33510 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
33520 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
33530 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65 61  d no data is rea
33540 64 2e 20 20 49 66 20 4e 20 6f 72 20 69 4f 66 66  d.  If N or iOff
33550 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  set is.** less t
33560 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c 49 54  han zero, [SQLIT
33570 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75  E_ERROR] is retu
33580 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61  rned and no data
33590 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20 54 68 65   is read..** The
335a0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 6c 6f   size of the blo
335b0 62 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65  b (and hence the
335c0 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f   maximum value o
335d0 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20  f N+iOffset).** 
335e0 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
335f0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
33600 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
33610 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
33620 0a 2a 2a 20 41 6e 20 61 74 74 65 6d 70 74 20 74  .** An attempt t
33630 6f 20 72 65 61 64 20 66 72 6f 6d 20 61 6e 20 65  o read from an e
33640 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e  xpired [BLOB han
33650 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20  dle] fails with 
33660 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  an.** error code
33670 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
33680 54 5d 2e 0a 2a 2a 0a 2a 2a 20 4f 6e 20 73 75 63  T]..**.** On suc
33690 63 65 73 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20  cess, SQLITE_OK 
336a0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
336b0 4f 74 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65  Otherwise, an [e
336c0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e  rror code] or an
336d0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
336e0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
336f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  ed..**.** This r
33700 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b  outine only work
33710 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e  s on a [BLOB han
33720 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62  dle] which has b
33730 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62  een created.** b
33740 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  y a prior succes
33750 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
33760 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
33770 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73  )] and which has
33780 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f   not.** been clo
33790 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
337a0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20  blob_close()].  
337b0 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  Passing any othe
337c0 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20  r pointer in.** 
337d0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
337e0 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
337f0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
33800 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  y undesirable be
33810 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  havior..**.** Se
33820 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
33830 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a  _blob_write()]..
33840 2a 2a 0a 2a 2a 20 52 65 71 75 69 72 65 6d 65 6e  **.** Requiremen
33850 74 73 3a 0a 2a 2a 20 5b 48 31 37 38 35 33 5d 20  ts:.** [H17853] 
33860 5b 48 31 37 38 35 36 5d 20 5b 48 31 37 38 35 39  [H17856] [H17859
33870 5d 20 5b 48 31 37 38 36 32 5d 20 5b 48 31 37 38  ] [H17862] [H178
33880 36 33 5d 20 5b 48 31 37 38 36 35 5d 20 5b 48 31  63] [H17865] [H1
33890 37 38 36 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  7868].*/.int sql
338a0 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 73  ite3_blob_read(s
338b0 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 76  qlite3_blob *, v
338c0 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c 20 69  oid *Z, int N, i
338d0 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a  nt iOffset);../*
338e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 57 72  .** CAPI3REF: Wr
338f0 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20 41 20  ite Data Into A 
33900 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
33910 6c 79 20 7b 48 31 37 38 37 30 7d 20 3c 53 33 30  ly {H17870} <S30
33920 32 33 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  230>.**.** This 
33930 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
33940 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20 69   to write data i
33950 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f  nto an open [BLO
33960 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20 61  B handle] from a
33970 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c  .** caller-suppl
33980 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79  ied buffer. N by
33990 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20  tes of data are 
339a0 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68 65 20  copied from the 
339b0 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e 74 6f  buffer Z.** into
339c0 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20   the open BLOB, 
339d0 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66 66 73  starting at offs
339e0 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a 0a 2a  et iOffset..**.*
339f0 2a 20 49 66 20 74 68 65 20 5b 42 4c 4f 42 20 68  * If the [BLOB h
33a00 61 6e 64 6c 65 5d 20 70 61 73 73 65 64 20 61 73  andle] passed as
33a10 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
33a20 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f 70 65 6e  ent was not open
33a30 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69 74 69 6e  ed for.** writin
33a40 67 20 28 74 68 65 20 66 6c 61 67 73 20 70 61 72  g (the flags par
33a50 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
33a60 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
33a70 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68  was zero),.** th
33a80 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
33a90 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44  rns [SQLITE_READ
33aa0 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ONLY]..**.** Thi
33ab0 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f  s function may o
33ac0 6e 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 63  nly modify the c
33ad0 6f 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 42  ontents of the B
33ae0 4c 4f 42 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f  LOB; it is.** no
33af0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e  t possible to in
33b00 63 72 65 61 73 65 20 74 68 65 20 73 69 7a 65 20  crease the size 
33b10 6f 66 20 61 20 42 4c 4f 42 20 75 73 69 6e 67 20  of a BLOB using 
33b20 74 68 69 73 20 41 50 49 2e 0a 2a 2a 20 49 66 20  this API..** If 
33b30 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 20 69  offset iOffset i
33b40 73 20 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79  s less than N by
33b50 74 65 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64  tes from the end
33b60 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a   of the BLOB,.**
33b70 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
33b80 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
33b90 6e 6f 20 64 61 74 61 20 69 73 20 77 72 69 74 74  no data is writt
33ba0 65 6e 2e 20 20 49 66 20 4e 20 69 73 0a 2a 2a 20  en.  If N is.** 
33bb0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b  less than zero [
33bc0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
33bd0 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
33be0 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e   data is written
33bf0 2e 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66  ..** The size of
33c00 20 74 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68   the BLOB (and h
33c10 65 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d  ence the maximum
33c20 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66   value of N+iOff
33c30 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64  set).** can be d
33c40 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
33c50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  the [sqlite3_blo
33c60 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
33c70 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61  face..**.** An a
33c80 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
33c90 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42  to an expired [B
33ca0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c  LOB handle] fail
33cb0 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72  s with an.** err
33cc0 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
33cd0 54 45 5f 41 42 4f 52 54 5d 2e 20 20 57 72 69 74  TE_ABORT].  Writ
33ce0 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 74  es to the BLOB t
33cf0 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20  hat occurred.** 
33d00 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42  before the [BLOB
33d10 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 64   handle] expired
33d20 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20   are not rolled 
33d30 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65  back by the.** e
33d40 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  xpiration of the
33d50 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20   handle, though 
33d60 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65 20  of course those 
33d70 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a  changes might.**
33d80 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72 77   have been overw
33d90 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 73 74  ritten by the st
33da0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78 70  atement that exp
33db0 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68 61  ired the BLOB ha
33dc0 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74  ndle.** or by ot
33dd0 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  her independent 
33de0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
33df0 2a 20 4f 6e 20 73 75 63 63 65 73 73 2c 20 53 51  * On success, SQ
33e00 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75 72  LITE_OK is retur
33e10 6e 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  ned..** Otherwis
33e20 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f  e, an  [error co
33e30 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e  de] or an [exten
33e40 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20  ded error code] 
33e50 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
33e60 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
33e70 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20  only works on a 
33e80 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68  [BLOB handle] wh
33e90 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65  ich has been cre
33ea0 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69  ated.** by a pri
33eb0 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
33ec0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
33ed0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  lob_open()] and 
33ee0 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a  which has not.**
33ef0 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20   been closed by 
33f00 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
33f10 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67  ose()].  Passing
33f20 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74   any other point
33f30 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73  er in.** to this
33f40 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73   routine results
33f50 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
33f60 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
33f70 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  irable behavior.
33f80 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
33f90 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
33fa0 65 61 64 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 52 65  ead()]..**.** Re
33fb0 71 75 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b  quirements:.** [
33fc0 48 31 37 38 37 33 5d 20 5b 48 31 37 38 37 34 5d  H17873] [H17874]
33fd0 20 5b 48 31 37 38 37 35 5d 20 5b 48 31 37 38 37   [H17875] [H1787
33fe0 36 5d 20 5b 48 31 37 38 37 37 5d 20 5b 48 31 37  6] [H17877] [H17
33ff0 38 37 39 5d 20 5b 48 31 37 38 38 32 5d 20 5b 48  879] [H17882] [H
34000 31 37 38 38 35 5d 0a 2a 2a 20 5b 48 31 37 38 38  17885].** [H1788
34010 38 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  8].*/.int sqlite
34020 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73 71 6c  3_blob_write(sql
34030 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63 6f 6e  ite3_blob *, con
34040 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e 74 20  st void *z, int 
34050 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  n, int iOffset);
34060 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34070 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65 20 53  : Virtual File S
34080 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 20 7b 48  ystem Objects {H
34090 31 31 32 30 30 7d 20 3c 53 32 30 31 30 30 3e 0a  11200} <S20100>.
340a0 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20  **.** A virtual 
340b0 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29  filesystem (VFS)
340c0 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   is an [sqlite3_
340d0 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74  vfs] object.** t
340e0 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20  hat SQLite uses 
340f0 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77  to interact.** w
34100 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ith the underlyi
34110 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
34120 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74  tem.  Most SQLit
34130 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69  e builds come wi
34140 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64  th a.** single d
34150 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 74 20  efault VFS that 
34160 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  is appropriate f
34170 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70  or the host comp
34180 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53  uter..** New VFS
34190 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  es can be regist
341a0 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e  ered and existin
341b0 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 75  g VFSes can be u
341c0 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20  nregistered..** 
341d0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  The following in
341e0 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
341f0 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  vided..**.** The
34200 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e   sqlite3_vfs_fin
34210 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  d() interface re
34220 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
34230 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20 69  to a VFS given i
34240 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 4e 61 6d 65  ts name..** Name
34250 73 20 61 72 65 20 63 61 73 65 20 73 65 6e 73 69  s are case sensi
34260 74 69 76 65 2e 0a 2a 2a 20 4e 61 6d 65 73 20 61  tive..** Names a
34270 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  re zero-terminat
34280 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
34290 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
342a0 20 6e 6f 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c   no match, a NUL
342b0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
342c0 75 72 6e 65 64 2e 0a 2a 2a 20 49 66 20 7a 56 66  urned..** If zVf
342d0 73 4e 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68  sName is NULL th
342e0 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  en the default V
342f0 46 53 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  FS is returned..
34300 2a 2a 0a 2a 2a 20 4e 65 77 20 56 46 53 65 73 20  **.** New VFSes 
34310 61 72 65 20 72 65 67 69 73 74 65 72 65 64 20 77  are registered w
34320 69 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  ith sqlite3_vfs_
34330 72 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 45  register()..** E
34340 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f  ach new VFS beco
34350 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20  mes the default 
34360 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44  VFS if the makeD
34370 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e  flt flag is set.
34380 0a 2a 2a 20 54 68 65 20 73 61 6d 65 20 56 46 53  .** The same VFS
34390 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
343a0 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
343b0 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79  s without injury
343c0 2e 0a 2a 2a 20 54 6f 20 6d 61 6b 65 20 61 6e 20  ..** To make an 
343d0 65 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e 74  existing VFS int
343e0 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  o the default VF
343f0 53 2c 20 72 65 67 69 73 74 65 72 20 69 74 20 61  S, register it a
34400 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  gain.** with the
34410 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20 73   makeDflt flag s
34420 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69 66 66  et.  If two diff
34430 65 72 65 6e 74 20 56 46 53 65 73 20 77 69 74 68  erent VFSes with
34440 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61 6d   the.** same nam
34450 65 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  e are registered
34460 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  , the behavior i
34470 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 49 66  s undefined.  If
34480 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65 67   a.** VFS is reg
34490 69 73 74 65 72 65 64 20 77 69 74 68 20 61 20 6e  istered with a n
344a0 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c 4c  ame that is NULL
344b0 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72   or an empty str
344c0 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ing,.** then the
344d0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
344e0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 55 6e  efined..**.** Un
344f0 72 65 67 69 73 74 65 72 20 61 20 56 46 53 20 77  register a VFS w
34500 69 74 68 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ith the sqlite3_
34510 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
34520 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
34530 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
34540 53 20 69 73 20 75 6e 72 65 67 69 73 74 65 72 65  S is unregistere
34550 64 2c 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69  d, another VFS i
34560 73 20 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74  s chosen as.** t
34570 68 65 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65  he default.  The
34580 20 63 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20   choice for the 
34590 6e 65 77 20 56 46 53 20 69 73 20 61 72 62 69 74  new VFS is arbit
345a0 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 52 65 71 75  rary..**.** Requ
345b0 69 72 65 6d 65 6e 74 73 3a 0a 2a 2a 20 5b 48 31  irements:.** [H1
345c0 31 32 30 33 5d 20 5b 48 31 31 32 30 36 5d 20 5b  1203] [H11206] [
345d0 48 31 31 32 30 39 5d 20 5b 48 31 31 32 31 32 5d  H11209] [H11212]
345e0 20 5b 48 31 31 32 31 35 5d 20 5b 48 31 31 32 31   [H11215] [H1121
345f0 38 5d 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 66  8].*/.sqlite3_vf
34600 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  s *sqlite3_vfs_f
34610 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ind(const char *
34620 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20 73  zVfsName);.int s
34630 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
34640 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ter(sqlite3_vfs*
34650 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29 3b  , int makeDflt);
34660 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66 73  .int sqlite3_vfs
34670 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c 69  _unregister(sqli
34680 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a 2a  te3_vfs*);../*.*
34690 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
346a0 78 65 73 20 7b 48 31 37 30 30 30 7d 20 3c 53 32  xes {H17000} <S2
346b0 30 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  0000>.**.** The 
346c0 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
346d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
346e0 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79  for thread.** sy
346f0 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54  nchronization. T
34700 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 69  hough they are i
34710 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65  ntended for inte
34720 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53  rnal.** use by S
34730 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74  QLite, code that
34740 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53   links against S
34750 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d  QLite is.** perm
34760 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79  itted to use any
34770 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
34780 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  es..**.** The SQ
34790 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65  Lite source code
347a0 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70   contains multip
347b0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
347c0 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d  ns.** of these m
347d0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20  utex routines.  
347e0 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69  An appropriate i
347f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
34800 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74   is selected aut
34810 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f  omatically at co
34820 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 54 68 65  mpile-time.  The
34830 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69 6d   following.** im
34840 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61 72  plementations ar
34850 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  e available in t
34860 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a 0a  he SQLite core:.
34870 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
34880 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  i>   SQLITE_MUTE
34890 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20  X_OS2.** <li>   
348a0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54 48  SQLITE_MUTEX_PTH
348b0 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  READ.** <li>   S
348c0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a  QLITE_MUTEX_W32.
348d0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
348e0 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20 3c  _MUTEX_NOOP.** <
348f0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
34900 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50  QLITE_MUTEX_NOOP
34910 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34920 69 73 20 61 20 73 65 74 20 6f 66 20 72 6f 75 74  is a set of rout
34930 69 6e 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 65  ines.** that doe
34940 73 20 6e 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e  s no real lockin
34950 67 20 61 6e 64 20 69 73 20 61 70 70 72 6f 70 72  g and is appropr
34960 69 61 74 65 20 66 6f 72 20 75 73 65 20 69 6e 0a  iate for use in.
34970 2a 2a 20 61 20 73 69 6e 67 6c 65 2d 74 68 72 65  ** a single-thre
34980 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
34990 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4d 55  .  The SQLITE_MU
349a0 54 45 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49  TEX_OS2,.** SQLI
349b0 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44  TE_MUTEX_PTHREAD
349c0 2c 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  , and SQLITE_MUT
349d0 45 58 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74  EX_W32 implement
349e0 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70  ations.** are ap
349f0 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73  propriate for us
34a00 65 20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c  e on OS/2, Unix,
34a10 20 61 6e 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a   and Windows..**
34a20 0a 2a 2a 20 49 66 20 53 51 4c 69 74 65 20 69 73  .** If SQLite is
34a30 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
34a40 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
34a50 41 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 73  APPDEF preproces
34a60 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66  sor.** macro def
34a70 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 51  ined (with "-DSQ
34a80 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45  LITE_MUTEX_APPDE
34a90 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d  F=1"), then no m
34aa0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
34ab0 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64  tation is includ
34ac0 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72  ed with the libr
34ad0 61 72 79 2e 20 49 6e 20 74 68 69 73 20 63 61 73  ary. In this cas
34ae0 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  e the.** applica
34af0 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
34b00 20 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 78 20   a custom mutex 
34b10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
34b20 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
34b30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
34b40 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  ] option of the 
34b50 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
34b60 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66   function.** bef
34b70 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69  ore calling sqli
34b80 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
34b90 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 70 75   or any other pu
34ba0 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a  blic sqlite3_.**
34bb0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63   function that c
34bc0 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
34bd0 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 0a 2a 2a  tialize()..**.**
34be0 20 7b 48 31 37 30 31 31 7d 20 54 68 65 20 73 71   {H17011} The sq
34bf0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
34c00 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c 6f  c() routine allo
34c10 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20 6d  cates a new.** m
34c20 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e 73  utex and returns
34c30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
34c40 2e 20 7b 48 31 37 30 31 32 7d 20 49 66 20 69 74  . {H17012} If it
34c50 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a 2a   returns NULL.**
34c60 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61 74   that means that
34c70 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20 6e   a mutex could n
34c80 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 2e  ot be allocated.
34c90 20 7b 48 31 37 30 31 33 7d 20 53 51 4c 69 74 65   {H17013} SQLite
34ca0 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e 64 20  .** will unwind 
34cb0 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20 72 65  its stack and re
34cc0 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e 20 7b  turn an error. {
34cd0 48 31 37 30 31 34 7d 20 54 68 65 20 61 72 67 75  H17014} The argu
34ce0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
34cf0 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
34d00 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   is one of these
34d10 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
34d20 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ts:.**.** <ul>.*
34d30 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
34d40 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69  UTEX_FAST.** <li
34d50 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
34d60 52 45 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69  RECURSIVE.** <li
34d70 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
34d80 53 54 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a  STATIC_MASTER.**
34d90 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
34da0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a  TEX_STATIC_MEM.*
34db0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
34dc0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32  UTEX_STATIC_MEM2
34dd0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
34de0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52  _MUTEX_STATIC_PR
34df0 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  NG.** <li>  SQLI
34e00 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
34e10 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  LRU.** <li>  SQL
34e20 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
34e30 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  _LRU2.** </ul>.*
34e40 2a 0a 2a 2a 20 7b 48 31 37 30 31 35 7d 20 54 68  *.** {H17015} Th
34e50 65 20 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73  e first two cons
34e60 74 61 6e 74 73 20 63 61 75 73 65 20 73 71 6c 69  tants cause sqli
34e70 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
34e80 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61  ) to create.** a
34e90 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 54 68 65   new mutex.  The
34ea0 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20 72 65   new mutex is re
34eb0 63 75 72 73 69 76 65 20 77 68 65 6e 20 53 51 4c  cursive when SQL
34ec0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
34ed0 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 20 62  IVE.** is used b
34ee0 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 69  ut not necessari
34ef0 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c 49 54  ly so when SQLIT
34f00 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 73 20  E_MUTEX_FAST is 
34f10 75 73 65 64 2e 20 7b 45 4e 44 7d 0a 2a 2a 20 54  used. {END}.** T
34f20 68 65 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  he mutex impleme
34f30 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ntation does not
34f40 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65 20 61 20   need to make a 
34f50 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
34f60 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 4d 55  etween SQLITE_MU
34f70 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 61 6e  TEX_RECURSIVE an
34f80 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  d SQLITE_MUTEX_F
34f90 41 53 54 20 69 66 20 69 74 20 64 6f 65 73 0a 2a  AST if it does.*
34fa0 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f 2e 20 20  * not want to.  
34fb0 7b 48 31 37 30 31 36 7d 20 42 75 74 20 53 51 4c  {H17016} But SQL
34fc0 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65  ite will only re
34fd0 71 75 65 73 74 20 61 20 72 65 63 75 72 73 69 76  quest a recursiv
34fe0 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61  e mutex in.** ca
34ff0 73 65 73 20 77 68 65 72 65 20 69 74 20 72 65 61  ses where it rea
35000 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20  lly needs one.  
35010 7b 45 4e 44 7d 20 49 66 20 61 20 66 61 73 74 65  {END} If a faste
35020 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76 65 20  r non-recursive 
35030 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65  mutex.** impleme
35040 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  ntation is avail
35050 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f 73 74  able on the host
35060 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 6d   platform, the m
35070 75 74 65 78 20 73 75 62 73 79 73 74 65 6d 0a 2a  utex subsystem.*
35080 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 73  * might return s
35090 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e 20 72  uch a mutex in r
350a0 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c 49 54  esponse to SQLIT
350b0 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a 2a 2a  E_MUTEX_FAST..**
350c0 0a 2a 2a 20 7b 48 31 37 30 31 37 7d 20 54 68 65  .** {H17017} The
350d0 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64 20 70   other allowed p
350e0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73 71 6c  arameters to sql
350f0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
35100 28 29 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a  () each return.*
35110 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
35120 20 73 74 61 74 69 63 20 70 72 65 65 78 69 73 74   static preexist
35130 69 6e 67 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d  ing mutex. {END}
35140 20 20 53 69 78 20 73 74 61 74 69 63 20 6d 75 74    Six static mut
35150 65 78 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  exes are.** used
35160 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
35170 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
35180 65 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  e.  Future versi
35190 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
351a0 20 6d 61 79 20 61 64 64 20 61 64 64 69 74 69 6f   may add additio
351b0 6e 61 6c 20 73 74 61 74 69 63 20 6d 75 74 65 78  nal static mutex
351c0 65 73 2e 20 20 53 74 61 74 69 63 20 6d 75 74 65  es.  Static mute
351d0 78 65 73 20 61 72 65 20 66 6f 72 20 69 6e 74 65  xes are for inte
351e0 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53  rnal.** use by S
351f0 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70  QLite only.  App
35200 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
35210 73 65 20 53 51 4c 69 74 65 20 6d 75 74 65 78 65  se SQLite mutexe
35220 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20  s should.** use 
35230 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61 6d 69 63  only the dynamic
35240 20 6d 75 74 65 78 65 73 20 72 65 74 75 72 6e 65   mutexes returne
35250 64 20 62 79 20 53 51 4c 49 54 45 5f 4d 55 54 45  d by SQLITE_MUTE
35260 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c  X_FAST or.** SQL
35270 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
35280 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 7b 48 31 37 30  IVE..**.** {H170
35290 31 38 7d 20 4e 6f 74 65 20 74 68 61 74 20 69 66  18} Note that if
352a0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 79 6e 61   one of the dyna
352b0 6d 69 63 20 6d 75 74 65 78 20 70 61 72 61 6d 65  mic mutex parame
352c0 74 65 72 73 20 28 53 51 4c 49 54 45 5f 4d 55 54  ters (SQLITE_MUT
352d0 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72 20 53 51  EX_FAST.** or SQ
352e0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
352f0 53 49 56 45 29 20 69 73 20 75 73 65 64 20 74 68  SIVE) is used th
35300 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  en sqlite3_mutex
35310 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72 65 74 75  _alloc().** retu
35320 72 6e 73 20 61 20 64 69 66 66 65 72 65 6e 74 20  rns a different 
35330 6d 75 74 65 78 20 6f 6e 20 65 76 65 72 79 20 63  mutex on every c
35340 61 6c 6c 2e 20 20 7b 48 31 37 30 33 34 7d 20 42  all.  {H17034} B
35350 75 74 20 66 6f 72 20 74 68 65 20 73 74 61 74 69  ut for the stati
35360 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79 70 65 73  c.** mutex types
35370 2c 20 74 68 65 20 73 61 6d 65 20 6d 75 74 65 78  , the same mutex
35380 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 6e 20   is returned on 
35390 65 76 65 72 79 20 63 61 6c 6c 20 74 68 61 74 20  every call that 
353a0 68 61 73 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  has.** the same 
353b0 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  type number..**.
353c0 2a 2a 20 7b 48 31 37 30 31 39 7d 20 54 68 65 20  ** {H17019} The 
353d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
353e0 65 65 28 29 20 72 6f 75 74 69 6e 65 20 64 65 61  ee() routine dea
353f0 6c 6c 6f 63 61 74 65 73 20 61 20 70 72 65 76 69  llocates a previ
35400 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ously.** allocat
35410 65 64 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78  ed dynamic mutex
35420 2e 20 7b 48 31 37 30 32 30 7d 20 53 51 4c 69 74  . {H17020} SQLit
35430 65 20 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20  e is careful to 
35440 64 65 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79  deallocate every
35450 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  .** dynamic mute
35460 78 20 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61  x that it alloca
35470 74 65 73 2e 20 7b 41 31 37 30 32 31 7d 20 54 68  tes. {A17021} Th
35480 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 65  e dynamic mutexe
35490 73 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 69 6e  s must not be in
354a0 0a 2a 2a 20 75 73 65 20 77 68 65 6e 20 74 68 65  .** use when the
354b0 79 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65  y are deallocate
354c0 64 2e 20 7b 41 31 37 30 32 32 7d 20 41 74 74 65  d. {A17022} Atte
354d0 6d 70 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f  mpting to deallo
354e0 63 61 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a  cate a static.**
354f0 20 6d 75 74 65 78 20 72 65 73 75 6c 74 73 20 69   mutex results i
35500 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
35510 76 69 6f 72 2e 20 7b 48 31 37 30 32 33 7d 20 53  vior. {H17023} S
35520 51 4c 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c  QLite never deal
35530 6c 6f 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61  locates.** a sta
35540 74 69 63 20 6d 75 74 65 78 2e 20 7b 45 4e 44 7d  tic mutex. {END}
35550 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35560 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
35570 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
35580 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65  ex_try() routine
35590 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20  s attempt.** to 
355a0 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 7b  enter a mutex. {
355b0 48 31 37 30 32 34 7d 20 49 66 20 61 6e 6f 74 68  H17024} If anoth
355c0 65 72 20 74 68 72 65 61 64 20 69 73 20 61 6c 72  er thread is alr
355d0 65 61 64 79 20 77 69 74 68 69 6e 20 74 68 65 20  eady within the 
355e0 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74 65  mutex,.** sqlite
355f0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 20  3_mutex_enter() 
35600 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20 73  will block and s
35610 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
35620 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  () will return.*
35630 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 7b  * SQLITE_BUSY. {
35640 48 31 37 30 32 35 7d 20 20 54 68 65 20 73 71 6c  H17025}  The sql
35650 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
35660 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35670 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a 2a  ns [SQLITE_OK].*
35680 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66 75  * upon successfu
35690 6c 20 65 6e 74 72 79 2e 20 20 7b 48 31 37 30 32  l entry.  {H1702
356a0 36 7d 20 4d 75 74 65 78 65 73 20 63 72 65 61 74  6} Mutexes creat
356b0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49  ed using.** SQLI
356c0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
356d0 56 45 20 63 61 6e 20 62 65 20 65 6e 74 65 72 65  VE can be entere
356e0 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
356f0 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72   by the same thr
35700 65 61 64 2e 0a 2a 2a 20 7b 48 31 37 30 32 37 7d  ead..** {H17027}
35710 20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20 74   In such cases t
35720 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75 73  he,.** mutex mus
35730 74 20 62 65 20 65 78 69 74 65 64 20 61 6e 20 65  t be exited an e
35740 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 74  qual number of t
35750 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f 74  imes before anot
35760 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63 61  her thread.** ca
35770 6e 20 65 6e 74 65 72 2e 20 20 7b 41 31 37 30 32  n enter.  {A1702
35780 38 7d 20 49 66 20 74 68 65 20 73 61 6d 65 20 74  8} If the same t
35790 68 72 65 61 64 20 74 72 69 65 73 20 74 6f 20 65  hread tries to e
357a0 6e 74 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a  nter any other.*
357b0 2a 20 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20  * kind of mutex 
357c0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
357d0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
357e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 7b 48  undefined..** {H
357f0 31 37 30 32 39 7d 20 53 51 4c 69 74 65 20 77 69  17029} SQLite wi
35800 6c 6c 20 6e 65 76 65 72 20 65 78 68 69 62 69 74  ll never exhibit
35810 0a 2a 2a 20 73 75 63 68 20 62 65 68 61 76 69 6f  .** such behavio
35820 72 20 69 6e 20 69 74 73 20 6f 77 6e 20 75 73 65  r in its own use
35830 20 6f 66 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a   of mutexes..**.
35840 2a 2a 20 53 6f 6d 65 20 73 79 73 74 65 6d 73 20  ** Some systems 
35850 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57 69  (for example, Wi
35860 6e 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f 74  ndows 95) do not
35870 20 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70 65   support the ope
35880 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ration.** implem
35890 65 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  ented by sqlite3
358a0 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f  _mutex_try().  O
358b0 6e 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c  n those systems,
358c0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
358d0 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77  ry().** will alw
358e0 61 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ays return SQLIT
358f0 45 5f 42 55 53 59 2e 20 20 7b 48 31 37 30 33 30  E_BUSY.  {H17030
35900 7d 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  } The SQLite cor
35910 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73  e only ever uses
35920 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
35930 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70  x_try() as an op
35940 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68  timization so th
35950 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  is is acceptable
35960 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
35970 20 7b 48 31 37 30 33 31 7d 20 54 68 65 20 73 71   {H17031} The sq
35980 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
35990 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74  e() routine exit
359a0 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77  s a mutex that w
359b0 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
359c0 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20   entered by the 
359d0 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 7b 41  same thread.  {A
359e0 31 37 30 33 32 7d 20 54 68 65 20 62 65 68 61 76  17032} The behav
359f0 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
35a00 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74 65 78  ned if the mutex
35a10 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
35a20 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65  y entered by the
35a30 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  .** calling thre
35a40 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63 75 72  ad or is not cur
35a50 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74 65 64  rently allocated
35a60 2e 20 20 7b 48 31 37 30 33 33 7d 20 53 51 4c 69  .  {H17033} SQLi
35a70 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72  te will.** never
35a80 20 64 6f 20 65 69 74 68 65 72 2e 20 7b 45 4e 44   do either. {END
35a90 7d 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 61  }.**.** If the a
35aa0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
35ab0 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
35ac0 2c 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  , sqlite3_mutex_
35ad0 74 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c  try(), or.** sql
35ae0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
35af0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
35b00 6e 74 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74  nter, then all t
35b10 68 72 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hree routines.**
35b20 20 62 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70   behave as no-op
35b30 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
35b40 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  o: [sqlite3_mute
35b50 78 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73  x_held()] and [s
35b60 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
35b70 68 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69  held()]..*/.sqli
35b80 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74  te3_mutex *sqlit
35b90 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69  e3_mutex_alloc(i
35ba0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
35bb0 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c  3_mutex_free(sql
35bc0 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f  ite3_mutex*);.vo
35bd0 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
35be0 5f 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d  _enter(sqlite3_m
35bf0 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  utex*);.int sqli
35c00 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71  te3_mutex_try(sq
35c10 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76  lite3_mutex*);.v
35c20 6f 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  oid sqlite3_mute
35c30 78 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f  x_leave(sqlite3_
35c40 6d 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  mutex*);../*.** 
35c50 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
35c60 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 20 7b  Methods Object {
35c70 48 31 37 31 32 30 7d 20 3c 53 32 30 31 33 30 3e  H17120} <S20130>
35c80 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
35c90 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
35ca0 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
35cb0 74 75 72 65 20 64 65 66 69 6e 65 73 20 74 68 65  ture defines the
35cc0 20 6c 6f 77 2d 6c 65 76 65 6c 20 72 6f 75 74 69   low-level routi
35cd0 6e 65 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 61  nes.** used to a
35ce0 6c 6c 6f 63 61 74 65 20 61 6e 64 20 75 73 65 20  llocate and use 
35cf0 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55  mutexes..**.** U
35d00 73 75 61 6c 6c 79 2c 20 74 68 65 20 64 65 66 61  sually, the defa
35d10 75 6c 74 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  ult mutex implem
35d20 65 6e 74 61 74 69 6f 6e 73 20 70 72 6f 76 69 64  entations provid
35d30 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 72 65  ed by SQLite are
35d40 0a 2a 2a 20 73 75 66 66 69 63 69 65 6e 74 2c 20  .** sufficient, 
35d50 68 6f 77 65 76 65 72 20 74 68 65 20 75 73 65 72  however the user
35d60 20 68 61 73 20 74 68 65 20 6f 70 74 69 6f 6e 20   has the option 
35d70 6f 66 20 73 75 62 73 74 69 74 75 74 69 6e 67 20  of substituting 
35d80 61 20 63 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c  a custom.** impl
35d90 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 73  ementation for s
35da0 70 65 63 69 61 6c 69 7a 65 64 20 64 65 70 6c 6f  pecialized deplo
35db0 79 6d 65 6e 74 73 20 6f 72 20 73 79 73 74 65 6d  yments or system
35dc0 73 20 66 6f 72 20 77 68 69 63 68 20 53 51 4c 69  s for which SQLi
35dd0 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 70  te.** does not p
35de0 72 6f 76 69 64 65 20 61 20 73 75 69 74 61 62 6c  rovide a suitabl
35df0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
35e00 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65 2c 20  . In this case, 
35e10 74 68 65 20 75 73 65 72 0a 2a 2a 20 63 72 65 61  the user.** crea
35e20 74 65 73 20 61 6e 64 20 70 6f 70 75 6c 61 74 65  tes and populate
35e30 73 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  s an instance of
35e40 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
35e50 74 6f 20 70 61 73 73 0a 2a 2a 20 74 6f 20 73 71  to pass.** to sq
35e60 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 61  lite3_config() a
35e70 6c 6f 6e 67 20 77 69 74 68 20 74 68 65 20 5b 53  long with the [S
35e80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
35e90 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  EX] option..** A
35ea0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20  dditionally, an 
35eb0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
35ec0 20 73 74 72 75 63 74 75 72 65 20 63 61 6e 20 62   structure can b
35ed0 65 20 75 73 65 64 20 61 73 20 61 6e 0a 2a 2a 20  e used as an.** 
35ee0 6f 75 74 70 75 74 20 76 61 72 69 61 62 6c 65 20  output variable 
35ef0 77 68 65 6e 20 71 75 65 72 79 69 6e 67 20 74 68  when querying th
35f00 65 20 73 79 73 74 65 6d 20 66 6f 72 20 74 68 65  e system for the
35f10 20 63 75 72 72 65 6e 74 20 6d 75 74 65 78 0a 2a   current mutex.*
35f20 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
35f30 2c 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  , using the [SQL
35f40 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
35f50 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a  TEX] option..**.
35f60 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49 6e 69  ** The xMutexIni
35f70 74 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64  t method defined
35f80 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75   by this structu
35f90 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73  re is invoked as
35fa0 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74  .** part of syst
35fb0 65 6d 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  em initializatio
35fc0 6e 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  n by the sqlite3
35fd0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 66 75  _initialize() fu
35fe0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 7b 48 31 37 30  nction..** {H170
35ff0 30 31 7d 20 54 68 65 20 78 4d 75 74 65 78 49 6e  01} The xMutexIn
36000 69 74 20 72 6f 75 74 69 6e 65 20 73 68 61 6c 6c  it routine shall
36010 20 62 65 20 63 61 6c 6c 65 64 20 62 79 20 53 51   be called by SQ
36020 4c 69 74 65 20 6f 6e 63 65 20 66 6f 72 20 65 61  Lite once for ea
36030 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20  ch.** effective 
36040 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
36050 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a  _initialize()]..
36060 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78  **.** The xMutex
36070 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69 6e  End method defin
36080 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63  ed by this struc
36090 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  ture is invoked 
360a0 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79  as.** part of sy
360b0 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62 79  stem shutdown by
360c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   the sqlite3_shu
360d0 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e  tdown() function
360e0 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  . The.** impleme
360f0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20  ntation of this 
36100 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 63 74  method is expect
36110 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c  ed to release al
36120 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a  l outstanding.**
36130 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61 69   resources obtai
36140 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 65 78  ned by the mutex
36150 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65   methods impleme
36160 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69 61  ntation, especia
36170 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74  lly.** those obt
36180 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d 75  ained by the xMu
36190 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20  texInit method. 
361a0 7b 48 31 37 30 30 33 7d 20 54 68 65 20 78 4d 75  {H17003} The xMu
361b0 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65  texEnd().** inte
361c0 72 66 61 63 65 20 73 68 61 6c 6c 20 62 65 20 69  rface shall be i
361d0 6e 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20  nvoked once for 
361e0 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b 73 71  each call to [sq
361f0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
36200 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 72 65 6d  ]..**.** The rem
36210 61 69 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74  aining seven met
36220 68 6f 64 73 20 64 65 66 69 6e 65 64 20 62 79 20  hods defined by 
36230 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 28  this structure (
36240 78 4d 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20  xMutexAlloc,.** 
36250 78 4d 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74  xMutexFree, xMut
36260 65 78 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54  exEnter, xMutexT
36270 72 79 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c  ry, xMutexLeave,
36280 20 78 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a   xMutexHeld and.
36290 2a 2a 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64  ** xMutexNotheld
362a0 29 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  ) implement the 
362b0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66  following interf
362c0 61 63 65 73 20 28 72 65 73 70 65 63 74 69 76 65  aces (respective
362d0 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ly):.**.** <ul>.
362e0 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
362f0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
36300 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c  )] </li>.**   <l
36310 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  i>  [sqlite3_mut
36320 65 78 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e  ex_free()] </li>
36330 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
36340 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
36350 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
36360 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
36370 74 65 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e  tex_try()] </li>
36380 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c  .**   <li>  [sql
36390 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
363a0 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c  ()] </li>.**   <
363b0 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75  li>  [sqlite3_mu
363c0 74 65 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69  tex_held()] </li
363d0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71  >.**   <li>  [sq
363e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
363f0 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  eld()] </li>.** 
36400 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
36410 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
36420 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62 6c  is that the publ
36430 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66  ic sqlite3_XXX f
36440 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61  unctions enumera
36450 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c  ted.** above sil
36460 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79  ently ignore any
36470 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61   invocations tha
36480 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f  t pass a NULL po
36490 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  inter instead.**
364a0 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
364b0 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d  x handle. The im
364c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
364d0 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66   the methods def
364e0 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20  ined.** by this 
364f0 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f  structure are no
36500 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 61  t required to ha
36510 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20  ndle this case, 
36520 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f  the results.** o
36530 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c  f passing a NULL
36540 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
36550 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
36560 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64  x handle are und
36570 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20  efined.** (i.e. 
36580 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  it is acceptable
36590 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69   to provide an i
365a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
365b0 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a  at segfaults if.
365c0 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 20  ** it is passed 
365d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e  a NULL pointer).
365e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65  .**.** The xMute
365f0 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 6d  xInit() method m
36600 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
36610 65 2e 20 20 49 74 20 6d 75 73 74 20 62 65 20 68  e.  It must be h
36620 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 69 6e  armless to.** in
36630 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 74 28  voke xMutexInit(
36640 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 73 20  ) mutiple times 
36650 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
36660 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69 74 68  process and with
36670 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 6e 69  out.** interveni
36680 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d 75 74  ng calls to xMut
36690 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f 6e 64  exEnd().  Second
366a0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
366b0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75 74  calls to.** xMut
366c0 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 62 65  exInit() must be
366d0 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 78   no-ops..**.** x
366e0 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74  MutexInit() must
366f0 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20   not use SQLite 
36700 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
36710 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  n ([sqlite3_mall
36720 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69 74 73  oc()].** and its
36730 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20 20 53   associates).  S
36740 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75 74 65 78  imilarly, xMutex
36750 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20 6e 6f 74  Alloc() must not
36760 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65 6d 6f   use SQLite memo
36770 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
36780 20 66 6f 72 20 61 20 73 74 61 74 69 63 20 6d 75   for a static mu
36790 74 65 78 2e 20 20 48 6f 77 65 76 65 72 20 78 4d  tex.  However xM
367a0 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61 79 20  utexAlloc() may 
367b0 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 65  use SQLite.** me
367c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
367d0 66 6f 72 20 61 20 66 61 73 74 20 6f 72 20 72 65  for a fast or re
367e0 63 75 72 73 69 76 65 20 6d 75 74 65 78 2e 0a 2a  cursive mutex..*
367f0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
36800 20 69 6e 76 6f 6b 65 20 74 68 65 20 78 4d 75 74   invoke the xMut
36810 65 78 45 6e 64 28 29 20 6d 65 74 68 6f 64 20 77  exEnd() method w
36820 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  hen [sqlite3_shu
36830 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a 2a 20 63  tdown()] is.** c
36840 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e 6c 79 20  alled, but only 
36850 69 66 20 74 68 65 20 70 72 69 6f 72 20 63 61 6c  if the prior cal
36860 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e 69 74 20  l to xMutexInit 
36870 72 65 74 75 72 6e 65 64 20 53 51 4c 49 54 45 5f  returned SQLITE_
36880 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75 74 65 78  OK..** If xMutex
36890 49 6e 69 74 20 66 61 69 6c 73 20 69 6e 20 61 6e  Init fails in an
368a0 79 20 77 61 79 2c 20 69 74 20 69 73 20 65 78 70  y way, it is exp
368b0 65 63 74 65 64 20 74 6f 20 63 6c 65 61 6e 20 75  ected to clean u
368c0 70 20 61 66 74 65 72 20 69 74 73 65 6c 66 0a 2a  p after itself.*
368d0 2a 20 70 72 69 6f 72 20 74 6f 20 72 65 74 75 72  * prior to retur
368e0 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ning..*/.typedef
368f0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
36900 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 73 71  mutex_methods sq
36910 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
36920 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
36930 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
36940 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  s {.  int (*xMut
36950 65 78 49 6e 69 74 29 28 76 6f 69 64 29 3b 0a 20  exInit)(void);. 
36960 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 45 6e 64   int (*xMutexEnd
36970 29 28 76 6f 69 64 29 3b 0a 20 20 73 71 6c 69 74  )(void);.  sqlit
36980 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78 4d 75 74  e3_mutex *(*xMut
36990 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29 3b 0a 20  exAlloc)(int);. 
369a0 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 46 72   void (*xMutexFr
369b0 65 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ee)(sqlite3_mute
369c0 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  x *);.  void (*x
369d0 4d 75 74 65 78 45 6e 74 65 72 29 28 73 71 6c 69  MutexEnter)(sqli
369e0 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
369f0 69 6e 74 20 28 2a 78 4d 75 74 65 78 54 72 79 29  int (*xMutexTry)
36a00 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
36a10 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74  );.  void (*xMut
36a20 65 78 4c 65 61 76 65 29 28 73 71 6c 69 74 65 33  exLeave)(sqlite3
36a30 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74  _mutex *);.  int
36a40 20 28 2a 78 4d 75 74 65 78 48 65 6c 64 29 28 73   (*xMutexHeld)(s
36a50 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
36a60 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 4e  .  int (*xMutexN
36a70 6f 74 68 65 6c 64 29 28 73 71 6c 69 74 65 33 5f  otheld)(sqlite3_
36a80 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a  mutex *);.};../*
36a90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
36aa0 74 65 78 20 56 65 72 69 66 69 63 61 74 69 6f 6e  tex Verification
36ab0 20 52 6f 75 74 69 6e 65 73 20 7b 48 31 37 30 38   Routines {H1708
36ac0 30 7d 20 3c 53 32 30 31 33 30 3e 20 3c 53 33 30  0} <S20130> <S30
36ad0 38 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  800>.**.** The s
36ae0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
36af0 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  d() and sqlite3_
36b00 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 20  mutex_notheld() 
36b10 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
36b20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
36b30 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28 29   inside assert()
36b40 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 7b 48 31   statements. {H1
36b50 37 30 38 31 7d 20 54 68 65 20 53 51 4c 69 74 65  7081} The SQLite
36b60 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20 75   core.** never u
36b70 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e  ses these routin
36b80 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64 65  es except inside
36b90 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e 64   an assert() and
36ba0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
36bb0 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f 20   are advised to 
36bc0 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64 20  follow the lead 
36bd0 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 7b 48  of the core.  {H
36be0 31 37 30 38 32 7d 20 54 68 65 20 63 6f 72 65 20  17082} The core 
36bf0 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73  only.** provides
36c00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
36c10 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
36c20 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 63  nes when it is c
36c30 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
36c40 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47  the SQLITE_DEBUG
36c50 20 66 6c 61 67 2e 20 20 7b 41 31 37 30 38 37 7d   flag.  {A17087}
36c60 20 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   External mutex 
36c70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a  implementations.
36c80 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71 75  ** are only requ
36c90 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 20  ired to provide 
36ca0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
36cb0 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20 69  f SQLITE_DEBUG i
36cc0 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e 64  s.** defined and
36cd0 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e 6f   if NDEBUG is no
36ce0 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  t defined..**.**
36cf0 20 7b 48 31 37 30 38 33 7d 20 54 68 65 73 65 20   {H17083} These 
36d00 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
36d10 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
36d20 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69  he mutex in thei
36d30 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73  r argument.** is
36d40 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c   held or not hel
36d50 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c  d, respectively,
36d60 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20   by the calling 
36d70 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 7b 58  thread..**.** {X
36d80 31 37 30 38 34 7d 20 54 68 65 20 69 6d 70 6c 65  17084} The imple
36d90 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f 74  mentation is not
36da0 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72 6f   required to pro
36db0 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20 6f  vided versions o
36dc0 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74 69  f these.** routi
36dd0 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 6c 6c  nes that actuall
36de0 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 20 69  y work. If the i
36df0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f  mplementation do
36e00 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 77  es not provide w
36e10 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69 6f  orking.** versio
36e20 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ns of these rout
36e30 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64 20  ines, it should 
36e40 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64 65  at least provide
36e50 20 73 74 75 62 73 20 74 68 61 74 20 61 6c 77 61   stubs that alwa
36e60 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 72 75  ys.** return tru
36e70 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64 6f  e so that one do
36e80 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72 69  es not get spuri
36e90 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20 66 61  ous assertion fa
36ea0 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 7b 48  ilures..**.** {H
36eb0 31 37 30 38 35 7d 20 49 66 20 74 68 65 20 61 72  17085} If the ar
36ec0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
36ed0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69  3_mutex_held() i
36ee0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
36ef0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75   then.** the rou
36f00 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75  tine should retu
36f10 72 6e 20 31 2e 20 20 7b 45 4e 44 7d 20 54 68 69  rn 1.  {END} Thi
36f20 73 20 73 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d  s seems counter-
36f30 69 6e 74 75 69 74 69 76 65 20 73 69 6e 63 65 0a  intuitive since.
36f40 2a 2a 20 63 6c 65 61 72 6c 79 20 74 68 65 20 6d  ** clearly the m
36f50 75 74 65 78 20 63 61 6e 6e 6f 74 20 62 65 20 68  utex cannot be h
36f60 65 6c 64 20 69 66 20 69 74 20 64 6f 65 73 20 6e  eld if it does n
36f70 6f 74 20 65 78 69 73 74 2e 20 20 42 75 74 20 74  ot exist.  But t
36f80 68 65 0a 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e  he.** the reason
36f90 20 74 68 65 20 6d 75 74 65 78 20 64 6f 65 73 20   the mutex does 
36fa0 6e 6f 74 20 65 78 69 73 74 20 69 73 20 62 65 63  not exist is bec
36fb0 61 75 73 65 20 74 68 65 20 62 75 69 6c 64 20 69  ause the build i
36fc0 73 20 6e 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d  s not.** using m
36fd0 75 74 65 78 65 73 2e 20 20 41 6e 64 20 77 65 20  utexes.  And we 
36fe0 64 6f 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  do not want the 
36ff0 61 73 73 65 72 74 28 29 20 63 6f 6e 74 61 69 6e  assert() contain
37000 69 6e 67 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20  ing the.** call 
37010 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
37020 5f 68 65 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c  _held() to fail,
37030 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72   so a non-zero r
37040 65 74 75 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20  eturn is.** the 
37050 61 70 70 72 6f 70 72 69 61 74 65 20 74 68 69 6e  appropriate thin
37060 67 20 74 6f 20 64 6f 2e 20 20 7b 48 31 37 30 38  g to do.  {H1708
37070 36 7d 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  6} The sqlite3_m
37080 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 0a 2a  utex_notheld().*
37090 2a 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f 75  * interface shou
370a0 6c 64 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 31  ld also return 1
370b0 20 77 68 65 6e 20 67 69 76 65 6e 20 61 20 4e 55   when given a NU
370c0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 69  LL pointer..*/.i
370d0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nt sqlite3_mutex
370e0 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75  _held(sqlite3_mu
370f0 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tex*);.int sqlit
37100 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
37110 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
37120 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37130 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73 20 7b  F: Mutex Types {
37140 48 31 37 30 30 31 7d 20 3c 48 31 37 30 30 30 3e  H17001} <H17000>
37150 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
37160 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
37170 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b  )] interface tak
37180 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
37190 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73  ment.** which is
371a0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
371b0 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e  teger constants.
371c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f  .**.** The set o
371d0 66 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  f static mutexes
371e0 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
371f0 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 65 6c 65   one SQLite rele
37200 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  ase to the.** ne
37210 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
37220 73 20 74 68 61 74 20 6f 76 65 72 72 69 64 65 20  s that override 
37230 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74  the built-in mut
37240 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 20 62 65  ex logic must be
37250 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 74 6f 20  .** prepared to 
37260 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69  accommodate addi
37270 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75  tional static mu
37280 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  texes..*/.#defin
37290 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  e SQLITE_MUTEX_F
372a0 41 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20  AST             
372b0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
372c0 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
372d0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
372e0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
372f0 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20  TATIC_MASTER    
37300 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
37310 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
37320 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71  M       3  /* sq
37330 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a  lite3_malloc() *
37340 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
37350 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
37360 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 4e 4f  M2      4  /* NO
37370 54 20 55 53 45 44 20 2a 2f 0a 23 64 65 66 69 6e  T USED */.#defin
37380 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
37390 54 41 54 49 43 5f 4f 50 45 4e 20 20 20 20 20 20  TATIC_OPEN      
373a0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 42 74 72  4  /* sqlite3Btr
373b0 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 64 65 66  eeOpen() */.#def
373c0 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
373d0 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20  _STATIC_PRNG    
373e0 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
373f0 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66  random() */.#def
37400 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
37410 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20  _STATIC_LRU     
37420 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65    6  /* lru page
37430 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   list */.#define
37440 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
37450 41 54 49 43 5f 4c 52 55 32 20 20 20 20 20 20 37  ATIC_LRU2      7
37460 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69    /* lru page li
37470 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  st */../*.** CAP
37480 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 65 20  I3REF: Retrieve 
37490 74 68 65 20 6d 75 74 65 78 20 66 6f 72 20 61 20  the mutex for a 
374a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
374b0 69 6f 6e 20 7b 48 31 37 30 30 32 7d 20 3c 48 31  ion {H17002} <H1
374c0 37 30 30 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  7000>.**.** This
374d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
374e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 68 65  ns a pointer the
374f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
37500 20 6f 62 6a 65 63 74 20 74 68 61 74 20 0a 2a 2a   object that .**
37510 20 73 65 72 69 61 6c 69 7a 65 73 20 61 63 63 65   serializes acce
37520 73 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  ss to the [datab
37530 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37540 67 69 76 65 6e 20 69 6e 20 74 68 65 20 61 72 67  given in the arg
37550 75 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 74 68  ument.** when th
37560 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
37570 65 5d 20 69 73 20 53 65 72 69 61 6c 69 7a 65 64  e] is Serialized
37580 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 74 68 72  ..** If the [thr
37590 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
375a0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 6f 72  Single-thread or
375b0 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 74 68   Multi-thread th
375c0 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  en this.** routi
375d0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
375e0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
375f0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c  lite3_mutex *sql
37600 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 28 73 71  ite3_db_mutex(sq
37610 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
37620 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65  CAPI3REF: Low-Le
37630 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44  vel Control Of D
37640 61 74 61 62 61 73 65 20 46 69 6c 65 73 20 7b 48  atabase Files {H
37650 31 31 33 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a  11300} <S30800>.
37660 2a 2a 0a 2a 2a 20 7b 48 31 31 33 30 31 7d 20 54  **.** {H11301} T
37670 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
37680 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
37690 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69  rface makes a di
376a0 72 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65  rect call to the
376b0 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  .** xFileControl
376c0 20 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20   method for the 
376d0 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
376e0 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f  ods] object asso
376f0 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61  ciated.** with a
37700 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
37710 62 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20  base identified 
37720 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  by the second ar
37730 67 75 6d 65 6e 74 2e 20 7b 48 31 31 33 30 32 7d  gument. {H11302}
37740 20 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20   The.** name of 
37750 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
37760 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
37770 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  d to the databas
37780 65 20 62 79 20 74 68 65 0a 2a 2a 20 3c 61 20 68  e by the.** <a h
37790 72 65 66 3d 22 6c 61 6e 67 5f 61 74 74 61 63 68  ref="lang_attach
377a0 2e 68 74 6d 6c 22 3e 41 54 54 41 43 48 3c 2f 61  .html">ATTACH</a
377b0 3e 20 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 68  > SQL command th
377c0 61 74 20 6f 70 65 6e 65 64 20 74 68 65 0a 2a 2a  at opened the.**
377d0 20 64 61 74 61 62 61 73 65 2e 20 7b 48 31 31 33   database. {H113
377e0 30 33 7d 20 54 6f 20 63 6f 6e 74 72 6f 6c 20 74  03} To control t
377f0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
37800 20 66 69 6c 65 2c 20 75 73 65 20 74 68 65 20 6e   file, use the n
37810 61 6d 65 20 22 6d 61 69 6e 22 0a 2a 2a 20 6f 72  ame "main".** or
37820 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
37830 20 7b 48 31 31 33 30 34 7d 20 54 68 65 20 74 68   {H11304} The th
37840 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
37850 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
37860 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65  s routine.** are
37870 20 70 61 73 73 65 64 20 64 69 72 65 63 74 6c 79   passed directly
37880 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
37890 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
378a0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a   parameters of.*
378b0 2a 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * the xFileContr
378c0 6f 6c 20 6d 65 74 68 6f 64 2e 20 20 7b 48 31 31  ol method.  {H11
378d0 33 30 35 7d 20 54 68 65 20 72 65 74 75 72 6e 20  305} The return 
378e0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69  value of the xFi
378f0 6c 65 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74  leControl.** met
37900 68 6f 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  hod becomes the 
37910 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
37920 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  this routine..**
37930 0a 2a 2a 20 7b 48 31 31 33 30 36 7d 20 49 66 20  .** {H11306} If 
37940 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
37950 65 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64  eter (zDbName) d
37960 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68  oes not match th
37970 65 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a  e name of any.**
37980 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66   open database f
37990 69 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ile, then SQLITE
379a0 5f 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e  _ERROR is return
379b0 65 64 2e 20 7b 48 31 31 33 30 37 7d 20 54 68 69  ed. {H11307} Thi
379c0 73 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  s error.** code 
379d0 69 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65  is not remembere
379e0 64 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62  d and will not b
379f0 65 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73  e recalled by [s
37a00 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
37a10 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
37a20 5f 65 72 72 6d 73 67 28 29 5d 2e 20 7b 41 31 31  _errmsg()]. {A11
37a30 33 30 38 7d 20 54 68 65 20 75 6e 64 65 72 6c 79  308} The underly
37a40 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  ing xFileControl
37a50 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a   method might.**
37a60 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c   also return SQL
37a70 49 54 45 5f 45 52 52 4f 52 2e 20 20 7b 41 31 31  ITE_ERROR.  {A11
37a80 33 30 39 7d 20 54 68 65 72 65 20 69 73 20 6e 6f  309} There is no
37a90 20 77 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75   way to distingu
37aa0 69 73 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61  ish between.** a
37ab0 6e 20 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e  n incorrect zDbN
37ac0 61 6d 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54  ame and an SQLIT
37ad0 45 5f 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66  E_ERROR return f
37ae0 72 6f 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69  rom the underlyi
37af0 6e 67 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72  ng.** xFileContr
37b00 6f 6c 20 6d 65 74 68 6f 64 2e 20 7b 45 4e 44 7d  ol method. {END}
37b10 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
37b20 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
37b30 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e 74  OCKSTATE].*/.int
37b40 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
37b50 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c 20  ntrol(sqlite3*, 
37b60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e  const char *zDbN
37b70 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  ame, int op, voi
37b80 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
37b90 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49 6e  3REF: Testing In
37ba0 74 65 72 66 61 63 65 20 7b 48 31 31 34 30 30 7d  terface {H11400}
37bb0 20 3c 53 33 30 38 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S30800>.**.** 
37bc0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 65 73 74  The sqlite3_test
37bd0 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e 74 65 72  _control() inter
37be0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
37bf0 72 65 61 64 20 6f 75 74 20 69 6e 74 65 72 6e 61  read out interna
37c00 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 20 53 51  l.** state of SQ
37c10 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 6e 6a 65  Lite and to inje
37c20 63 74 20 66 61 75 6c 74 73 20 69 6e 74 6f 20 53  ct faults into S
37c30 51 4c 69 74 65 20 66 6f 72 20 74 65 73 74 69 6e  QLite for testin
37c40 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e 20 20  g.** purposes.  
37c50 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
37c60 74 65 72 20 69 73 20 61 6e 20 6f 70 65 72 61 74  ter is an operat
37c70 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 20 64 65  ion code that de
37c80 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 65 20  termines.** the 
37c90 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 6e 67 2c  number, meaning,
37ca0 20 61 6e 64 20 6f 70 65 72 61 74 69 6f 6e 20 6f   and operation o
37cb0 66 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  f all subsequent
37cc0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a 0a   parameters..**.
37cd0 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
37ce0 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 75 73 65  e is not for use
37cf0 20 62 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   by applications
37d00 2e 20 20 49 74 20 65 78 69 73 74 73 20 73 6f 6c  .  It exists sol
37d10 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 72 69 66  ely.** for verif
37d20 79 69 6e 67 20 74 68 65 20 63 6f 72 72 65 63 74  ying the correct
37d30 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
37d40 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
37d50 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a 2a 2a 20  .  Depending.** 
37d60 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 4c 69 74  on how the SQLit
37d70 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f 6d  e library is com
37d80 70 69 6c 65 64 2c 20 74 68 69 73 20 69 6e 74 65  piled, this inte
37d90 72 66 61 63 65 20 6d 69 67 68 74 20 6e 6f 74 20  rface might not 
37da0 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  exist..**.** The
37db0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
37dc0 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 73 2c  operation codes,
37dd0 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73 2c   their meanings,
37de0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 0a   the parameters.
37df0 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c 20 61 6e  ** they take, an
37e00 64 20 77 68 61 74 20 74 68 65 79 20 64 6f 20 61  d what they do a
37e10 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 74 20 74  re all subject t
37e20 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
37e30 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e 6c 69   notice..** Unli
37e40 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 53  ke most of the S
37e50 51 4c 69 74 65 20 41 50 49 2c 20 74 68 69 73 20  QLite API, this 
37e60 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20  function is not 
37e70 67 75 61 72 61 6e 74 65 65 64 20 74 6f 0a 2a 2a  guaranteed to.**
37e80 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 69 73 74   operate consist
37e90 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e 65 20 72  ently from one r
37ea0 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
37eb0 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  xt..*/.int sqlit
37ec0 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28  e3_test_control(
37ed0 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
37ee0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
37ef0 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65  esting Interface
37f00 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64 65 73   Operation Codes
37f10 20 7b 48 31 31 34 31 30 7d 20 3c 48 31 31 34 30   {H11410} <H1140
37f20 30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  0>.**.** These c
37f30 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
37f40 20 76 61 6c 69 64 20 6f 70 65 72 61 74 69 6f 6e   valid operation
37f50 20 63 6f 64 65 20 70 61 72 61 6d 65 74 65 72 73   code parameters
37f60 20 75 73 65 64 0a 2a 2a 20 61 73 20 74 68 65 20   used.** as the 
37f70 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
37f80 6f 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  o [sqlite3_test_
37f90 63 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a  control()]..**.*
37fa0 2a 20 54 68 65 73 65 20 70 61 72 61 6d 65 74 65  * These paramete
37fb0 72 73 20 61 6e 64 20 74 68 65 69 72 20 6d 65 61  rs and their mea
37fc0 6e 69 6e 67 73 20 61 72 65 20 73 75 62 6a 65 63  nings are subjec
37fd0 74 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 77  t to change.** w
37fe0 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 20 20  ithout notice.  
37ff0 54 68 65 73 65 20 76 61 6c 75 65 73 20 61 72 65  These values are
38000 20 66 6f 72 20 74 65 73 74 69 6e 67 20 70 75 72   for testing pur
38010 70 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41  poses only..** A
38020 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
38030 6c 64 20 6e 6f 74 20 75 73 65 20 61 6e 79 20 6f  ld not use any o
38040 66 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65  f these paramete
38050 72 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71  rs or the.** [sq
38060 6c 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72  lite3_test_contr
38070 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
38080 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
38090 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47  TE_TESTCTRL_PRNG
380a0 5f 53 41 56 45 20 20 20 20 20 20 20 20 20 20 20  _SAVE           
380b0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
380c0 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50  QLITE_TESTCTRL_P
380d0 52 4e 47 5f 52 45 53 54 4f 52 45 20 20 20 20 20  RNG_RESTORE     
380e0 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
380f0 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
38100 4c 5f 50 52 4e 47 5f 52 45 53 45 54 20 20 20 20  L_PRNG_RESET    
38110 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
38120 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
38130 43 54 52 4c 5f 42 49 54 56 45 43 5f 54 45 53 54  CTRL_BITVEC_TEST
38140 20 20 20 20 20 20 20 20 20 20 20 20 20 20 38 0a                8.
38150 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
38160 45 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f 49 4e  ESTCTRL_FAULT_IN
38170 53 54 41 4c 4c 20 20 20 20 20 20 20 20 20 20 20  STALL           
38180 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
38190 45 5f 54 45 53 54 43 54 52 4c 5f 42 45 4e 49 47  E_TESTCTRL_BENIG
381a0 4e 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 20 20  N_MALLOC_HOOKS  
381b0 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
381c0 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 45  LITE_TESTCTRL_PE
381d0 4e 44 49 4e 47 5f 42 59 54 45 20 20 20 20 20 20  NDING_BYTE      
381e0 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65        11.#define
381f0 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
38200 5f 41 53 53 45 52 54 20 20 20 20 20 20 20 20 20  _ASSERT         
38210 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
38220 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
38230 54 52 4c 5f 41 4c 57 41 59 53 20 20 20 20 20 20  TRL_ALWAYS      
38240 20 20 20 20 20 20 20 20 20 20 20 20 31 33 0a 23              13.#
38250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
38260 53 54 43 54 52 4c 5f 52 45 53 45 52 56 45 20 20  STCTRL_RESERVE  
38270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
38280 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
38290 46 3a 20 53 51 4c 69 74 65 20 52 75 6e 74 69 6d  F: SQLite Runtim
382a0 65 20 53 74 61 74 75 73 20 7b 48 31 37 32 30 30  e Status {H17200
382b0 7d 20 3c 53 36 30 32 30 30 3e 0a 2a 2a 20 45 58  } <S60200>.** EX
382c0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
382d0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
382e0 69 73 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  is used to retri
382f0 65 76 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74  eve runtime stat
38300 75 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  us information.*
38310 2a 20 61 62 6f 75 74 20 74 68 65 20 70 72 65 66  * about the pref
38320 6f 72 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 74  ormance of SQLit
38330 65 2c 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c  e, and optionall
38340 79 20 74 6f 20 72 65 73 65 74 20 76 61 72 69 6f  y to reset vario
38350 75 73 0a 2a 2a 20 68 69 67 68 77 61 74 65 72 20  us.** highwater 
38360 6d 61 72 6b 73 2e 20 20 54 68 65 20 66 69 72 73  marks.  The firs
38370 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
38380 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f   integer code fo
38390 72 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 66 69  r.** the specifi
383a0 63 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 6d  c parameter to m
383b0 65 61 73 75 72 65 2e 20 20 52 65 63 6f 67 6e 69  easure.  Recogni
383c0 7a 65 64 20 69 6e 74 65 67 65 72 20 63 6f 64 65  zed integer code
383d0 73 0a 2a 2a 20 61 72 65 20 6f 66 20 74 68 65 20  s.** are of the 
383e0 66 6f 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41  form [SQLITE_STA
383f0 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20  TUS_MEMORY_USED 
38400 7c 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  | SQLITE_STATUS_
38410 2e 2e 2e 5d 2e 0a 2a 2a 20 54 68 65 20 63 75 72  ...]..** The cur
38420 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74 68  rent value of th
38430 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 72  e parameter is r
38440 65 74 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70 43  eturned into *pC
38450 75 72 72 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 68  urrent..** The h
38460 69 67 68 65 73 74 20 72 65 63 6f 72 64 65 64 20  ighest recorded 
38470 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
38480 64 20 69 6e 20 2a 70 48 69 67 68 77 61 74 65 72  d in *pHighwater
38490 2e 20 20 49 66 20 74 68 65 0a 2a 2a 20 72 65 73  .  If the.** res
384a0 65 74 46 6c 61 67 20 69 73 20 74 72 75 65 2c 20  etFlag is true, 
384b0 74 68 65 6e 20 74 68 65 20 68 69 67 68 65 73 74  then the highest
384c0 20 72 65 63 6f 72 64 20 76 61 6c 75 65 20 69 73   record value is
384d0 20 72 65 73 65 74 20 61 66 74 65 72 0a 2a 2a 20   reset after.** 
384e0 2a 70 48 69 67 68 77 61 74 65 72 20 69 73 20 77  *pHighwater is w
384f0 72 69 74 74 65 6e 2e 20 53 6f 6d 65 20 70 61 72  ritten. Some par
38500 61 6d 65 74 65 72 73 20 64 6f 20 6e 6f 74 20 72  ameters do not r
38510 65 63 6f 72 64 20 74 68 65 20 68 69 67 68 65 73  ecord the highes
38520 74 0a 2a 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72  t.** value.  For
38530 20 74 68 6f 73 65 20 70 61 72 61 6d 65 74 65 72   those parameter
38540 73 0a 2a 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20  s.** nothing is 
38550 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48  written into *pH
38560 69 67 68 77 61 74 65 72 20 61 6e 64 20 74 68 65  ighwater and the
38570 20 72 65 73 65 74 46 6c 61 67 20 69 73 20 69 67   resetFlag is ig
38580 6e 6f 72 65 64 2e 0a 2a 2a 20 4f 74 68 65 72 20  nored..** Other 
38590 70 61 72 61 6d 65 74 65 72 73 20 72 65 63 6f 72  parameters recor
385a0 64 20 6f 6e 6c 79 20 74 68 65 20 68 69 67 68 77  d only the highw
385b0 61 74 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e 6f  ater mark and no
385c0 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  t the current.**
385d0 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68 65   value.  For the
385e0 73 65 20 6c 61 74 74 65 72 20 70 61 72 61 6d 65  se latter parame
385f0 74 65 72 73 20 6e 6f 74 68 69 6e 67 20 69 73 20  ters nothing is 
38600 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 43  written into *pC
38610 75 72 72 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  urrent..**.** Th
38620 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
38630 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 20 6f 6e 20  ns SQLITE_OK on 
38640 73 75 63 63 65 73 73 20 61 6e 64 20 61 20 6e 6f  success and a no
38650 6e 2d 7a 65 72 6f 0a 2a 2a 20 5b 65 72 72 6f 72  n-zero.** [error
38660 20 63 6f 64 65 5d 20 6f 6e 20 66 61 69 6c 75 72   code] on failur
38670 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  e..**.** This ro
38680 75 74 69 6e 65 20 69 73 20 74 68 72 65 61 64 73  utine is threads
38690 61 66 65 20 62 75 74 20 69 73 20 6e 6f 74 20 61  afe but is not a
386a0 74 6f 6d 69 63 2e 20 20 54 68 69 73 20 72 6f 75  tomic.  This rou
386b0 74 69 6e 65 20 63 61 6e 20 62 65 0a 2a 2a 20 63  tine can be.** c
386c0 61 6c 6c 65 64 20 77 68 69 6c 65 20 6f 74 68 65  alled while othe
386d0 72 20 74 68 72 65 61 64 73 20 61 72 65 20 72 75  r threads are ru
386e0 6e 6e 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6f  nning the same o
386f0 72 20 64 69 66 66 65 72 65 6e 74 20 53 51 4c 69  r different SQLi
38700 74 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  te.** interfaces
38710 2e 20 20 48 6f 77 65 76 65 72 20 74 68 65 20 76  .  However the v
38720 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 69  alues returned i
38730 6e 20 2a 70 43 75 72 72 65 6e 74 20 61 6e 64 0a  n *pCurrent and.
38740 2a 2a 20 2a 70 48 69 67 68 77 61 74 65 72 20 72  ** *pHighwater r
38750 65 66 6c 65 63 74 20 74 68 65 20 73 74 61 74 75  eflect the statu
38760 73 20 6f 66 20 53 51 4c 69 74 65 20 61 74 20 64  s of SQLite at d
38770 69 66 66 65 72 65 6e 74 20 70 6f 69 6e 74 73 20  ifferent points 
38780 69 6e 20 74 69 6d 65 0a 2a 2a 20 61 6e 64 20 69  in time.** and i
38790 74 20 69 73 20 70 6f 73 73 69 62 6c 65 20 74 68  t is possible th
387a0 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
387b0 64 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  d might change t
387c0 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
387d0 69 6e 20 62 65 74 77 65 65 6e 20 74 68 65 20 74  in between the t
387e0 69 6d 65 73 20 77 68 65 6e 20 2a 70 43 75 72 72  imes when *pCurr
387f0 65 6e 74 20 61 6e 64 20 2a 70 48 69 67 68 77 61  ent and *pHighwa
38800 74 65 72 20 61 72 65 20 77 72 69 74 74 65 6e 2e  ter are written.
38810 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
38820 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
38830 74 75 73 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  tus()].*/.SQLITE
38840 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 6