/ Hex Artifact Content
Login

Artifact 0c73df1f6e82e18e24b5abe8a561abfa6d098b96:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 74 65 73 20 74 6f 0a 2a  ro evalutes to.*
0e50: 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  * a string which
0e60: 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61   identifies a pa
0e70: 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69  rticular check-i
0e80: 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  n of SQLite.** w
0e90: 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67  ithin its config
0ea0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0eb0: 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65  nt system.  ^The
0ec0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
0ed0: 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  D.** string cont
0ee0: 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e  ains the date an
0ef0: 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68  d time of the ch
0f00: 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64  eck-in (UTC) and
0f10: 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73 68   an SHA1.** hash
0f20: 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20 73   of the entire s
0f30: 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a  ource tree..**.*
0f40: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
0f50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
0f60: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
0f70: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
0f80: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  r()], [sqlite3_s
0f90: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b  ourceid()],.** [
0fa0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
0fb0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
0fc0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23  urce_id()]..*/.#
0fd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45  define SQLITE_VE
0fe0: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d  RSION        "--
0ff0: 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20  VERS--".#define 
1000: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1010: 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d  UMBER --VERSION-
1020: 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65  NUMBER--.#define
1030: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
1040: 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43 45  D      "--SOURCE
1050: 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  -ID--"../*.** CA
1060: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1070: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
1080: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
1090: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
10a0: 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  rsion.**.** Thes
10b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f  e interfaces pro
10c0: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e  vide the same in
10d0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65  formation as the
10e0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
10f0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  ],.** [SQLITE_VE
1100: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61  RSION_NUMBER], a
1110: 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  nd [SQLITE_SOURC
1120: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1130: 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62  ssor macros.** b
1140: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65  ut are associate
1150: 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
1160: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
1170: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
1180: 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72  ^(Cautious.** pr
1190: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
11a0: 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29  include assert()
11b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
11c0: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  heir application
11d0: 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68   to.** verify th
11e0: 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  at values return
11f0: 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65  ed by these inte
1200: 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65  rfaces match the
1210: 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68   macros in.** th
1220: 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68  e header, and th
1230: 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20 74  us insure that t
1240: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
1250: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
1260: 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72  th matching libr
1270: 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66  ary and header f
1280: 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  iles..**.** <blo
1290: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
12a0: 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33   assert( sqlite3
12b0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
12c0: 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52  er()==SQLITE_VER
12d0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a  SION_NUMBER );.*
12e0: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
12f0: 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  (sqlite3_sourcei
1300: 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43  d(),SQLITE_SOURC
1310: 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61  E_ID)==0 );.** a
1320: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71  ssert( strcmp(sq
1330: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1340: 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  (),SQLITE_VERSIO
1350: 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72  N)==0 );.** </pr
1360: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
1370: 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
1380: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
1390: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63  tring constant c
13a0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74  ontains the text
13b0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   of [SQLITE_VERS
13c0: 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20  ION].** macro.  
13d0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62  ^The sqlite3_lib
13e0: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
13f0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  on returns a poi
1400: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74  nter to the.** t
1410: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65  o the sqlite3_ve
1420: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1430: 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71  onstant.  The sq
1440: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1450: 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ().** function i
1460: 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75  s provided for u
1470: 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65  se in DLLs since
1480: 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c   DLL users usual
1490: 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a  ly do not have.*
14a0: 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20  * direct access 
14b0: 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  to string consta
14c0: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44  nts within the D
14d0: 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  LL.  ^The.** sql
14e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
14f0: 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f  number() functio
1500: 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  n returns an int
1510: 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a  eger equal to.**
1520: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
1530: 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20  _NUMBER].  ^The 
1540: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
1550: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 20 70 6f  () function a po
1560: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 20 73 74  inter.** to a st
1570: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
1580: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1590: 20 73 61 6d 65 20 61 73 20 74 68 65 20 5b 53 51   same as the [SQ
15a0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 0a  LITE_SOURCE_ID].
15b0: 2a 2a 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  ** C preprocesso
15c0: 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  r macro..**.** S
15d0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
15e0: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
15f0: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
1600: 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  d()]..*/.SQLITE_
1610: 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61  EXTERN const cha
1620: 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  r sqlite3_versio
1630: 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  n[];.const char 
1640: 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  *sqlite3_libvers
1650: 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74  ion(void);.const
1660: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1670: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69  ourceid(void);.i
1680: 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  nt sqlite3_libve
1690: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69  rsion_number(voi
16a0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
16b0: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65  REF: Test To See
16c0: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20   If The Library 
16d0: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a  Is Threadsafe.**
16e0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
16f0: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
1700: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a  nction returns z
1710: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ero if and only 
1720: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73  if.** SQLite was
1730: 20 63 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69   compiled mutexi
1740: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1750: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1760: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1770: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1780: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1790: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
17a0: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
17b0: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
17c0: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
17d0: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
17e0: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
17f0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1800: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1810: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1820: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1830: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1840: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1850: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1860: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1870: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1880: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1890: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
18a0: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
18b0: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
18c0: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
18d0: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
18e0: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
18f0: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1900: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1910: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1920: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1930: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1940: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1950: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1960: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1970: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1980: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1990: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
19a0: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
19b0: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
19c0: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
19d0: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
19e0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
19f0: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1a00: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1a10: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1a20: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1a30: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1a40: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1a50: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1a60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1a70: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1a80: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1a90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1aa0: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1ab0: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1ac0: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1ad0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1ae0: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1af0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1b00: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1b10: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1b20: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1b30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1b40: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1b50: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
1b60: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
1b70: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
1b80: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
1b90: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
1ba0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
1bb0: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
1bc0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
1bd0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
1be0: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
1bf0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
1c00: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
1c10: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
1c20: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
1c30: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
1c40: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
1c50: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
1c60: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
1c70: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
1c80: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
1c90: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
1ca0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
1cb0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
1cc0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
1cd0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
1ce0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
1cf0: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1d00: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
1d10: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
1d20: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
1d30: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
1d40: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
1d50: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
1d60: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
1d70: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
1d80: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1d90: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1da0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
1db0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1dc0: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
1dd0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
1de0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
1df0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e00: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
1e10: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
1e20: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
1e30: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
1e40: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
1e50: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
1e60: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
1e70: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
1e80: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
1e90: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
1ea0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
1eb0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
1ec0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
1ed0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
1ee0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
1ef0: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
1f00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
1f10: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
1f20: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
1f30: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
1f40: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73  3_close()].** is
1f50: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
1f60: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
1f70: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
1f80: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
1f90: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fa0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
1fb0: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
1fc0: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1fd0: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1fe0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
1ff0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
2000: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
2010: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
2020: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2030: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
2040: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
2050: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2060: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2070: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2080: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2090: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
20a0: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
20b0: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
20c0: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
20d0: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
20e0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
20f0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
2100: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
2110: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
2120: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
2130: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
2140: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
2150: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2160: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2170: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2180: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2190: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
21a0: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
21b0: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
21c0: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
21d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
21e0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
21f0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
2200: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
2210: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
2220: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
2230: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
2240: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2250: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2260: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2270: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2280: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2290: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
22a0: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
22b0: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
22c0: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
22d0: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
22e0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
22f0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
2300: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2310: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
2320: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2330: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
2340: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
2350: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2360: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2370: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2380: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2390: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
23a0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
23b0: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
23c0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
23d0: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
23e0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
23f0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2400: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
2410: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2420: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
2430: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
2440: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
2450: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2460: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2470: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2480: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2490: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
24a0: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
24b0: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
24c0: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
24d0: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
24e0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
24f0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
2500: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
2510: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
2520: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
2530: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2540: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
2550: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2560: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2570: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2580: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2590: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
25a0: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
25b0: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
25c0: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
25d0: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
25e0: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
25f0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2600: 20 73 75 63 63 65 73 73 66 75 6c 6c 6c 79 20 64   successfullly d
2610: 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c  estroyed and all
2620: 20 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f   associated reso
2630: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2640: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  cated..**.** App
2650: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b  lications must [
2660: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2670: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2680: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2690: 6d 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ments].** and [s
26a0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
26b0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
26c0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73  BLOB handles] as
26d0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
26e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
26f0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2700: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2710: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2720: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2730: 6c 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64  lose() is called
2740: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2750: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2760: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2770: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2780: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
2790: 6f 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  or [BLOB handles
27a0: 5d 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72  ], then it retur
27b0: 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53  ns.** SQLITE_BUS
27c0: 59 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71  Y..**.** ^If [sq
27d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69  lite3_close()] i
27e0: 73 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20  s invoked while 
27f0: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2800: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
2810: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
2820: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2830: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
2840: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
2850: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2860: 43 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68  C)] must be eith
2870: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
2880: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
2890: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
28a0: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
28b0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
28c0: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
28d0: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
28e0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
28f0: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
2900: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
2910: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
2920: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74  ite3_close() wit
2930: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
2940: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a   argument is a .
2950: 2a 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  ** harmless no-o
2960: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
2970: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20  3_close(sqlite3 
2980: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  *);../*.** The t
2990: 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61  ype for a callba
29a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  ck function..** 
29b0: 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61  This is legacy a
29c0: 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20  nd deprecated.  
29d0: 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66  It is included f
29e0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a  or historical.**
29f0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61   compatibility a
2a00: 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65  nd is not docume
2a10: 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  nted..*/.typedef
2a20: 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63   int (*sqlite3_c
2a30: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
2a40: 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a  nt,char**, char*
2a50: 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2a60: 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75  REF: One-Step Qu
2a70: 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e  ery Execution In
2a80: 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68  terface.**.** Th
2a90: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
2aa0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20   interface is a 
2ab0: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70  convenience wrap
2ac0: 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
2ad0: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ae0: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73  2()], [sqlite3_s
2af0: 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  tep()], and [sql
2b00: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b10: 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73  ,.** that allows
2b20: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2b30: 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20  to run multiple 
2b40: 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51  statements of SQ
2b50: 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76  L.** without hav
2b60: 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74  ing to use a lot
2b70: 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a   of C code. .**.
2b80: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b90: 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65  exec() interface
2ba0: 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   runs zero or mo
2bb0: 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  re UTF-8 encoded
2bc0: 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  ,.** semicolon-s
2bd0: 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74  eparate SQL stat
2be0: 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e  ements passed in
2bf0: 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  to its 2nd argum
2c00: 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63  ent,.** in the c
2c10: 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64  ontext of the [d
2c20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c30: 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73  on] passed in as
2c40: 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75   its 1st.** argu
2c50: 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63  ment.  ^If the c
2c60: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2c70: 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75   of the 3rd argu
2c80: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
2c90: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74  e3_exec() is not
2ca0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69   NULL, then it i
2cb0: 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61  s invoked for ea
2cc0: 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a  ch result row.**
2cd0: 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74   coming out of t
2ce0: 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c  he evaluated SQL
2cf0: 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54   statements.  ^T
2d00: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
2d10: 74 6f 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  to.** to sqlite3
2d20: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
2d30: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
2d40: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
2d50: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
2d60: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
2d70: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
2d80: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
2d90: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
2da0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
2db0: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
2dc0: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
2dd0: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
2de0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
2df0: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
2e00: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
2e10: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
2e20: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
2e30: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
2e40: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
2e50: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
2e60: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
2e70: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
2e80: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
2e90: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
2ea0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
2eb0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
2ec0: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
2ed0: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
2ee0: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
2ef0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
2f00: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
2f10: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2f20: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
2f30: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
2f40: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
2f50: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
2f60: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
2f70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
2f80: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
2f90: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
2fa0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
2fb0: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
2fc0: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
2fd0: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
2fe0: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
2ff0: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
3000: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3010: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
3020: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
3030: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3040: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3050: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3060: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3070: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3080: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3090: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
30a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
30b0: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
30c0: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
30d0: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
30e0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
30f0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3100: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3110: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3120: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3130: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3140: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3150: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3160: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3170: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3180: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3190: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
31a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
31b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
31c0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
31d0: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
31e0: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
31f0: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3200: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3210: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3220: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3230: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3240: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3250: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3260: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3270: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3280: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3290: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
32a0: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
32b0: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
32c0: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
32d0: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
32e0: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
32f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3300: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3310: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3320: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3330: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3340: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3350: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3360: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3370: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3380: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3390: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
33a0: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
33b0: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
33c0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
33d0: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
33e0: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
33f0: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3400: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3410: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3420: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3430: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3440: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3450: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
3460: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
3470: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
3480: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
3490: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
34a0: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
34b0: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
34c0: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
34d0: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
34e0: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
34f0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3500: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3510: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3520: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3530: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3540: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3550: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3560: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3570: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3580: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3590: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
35a0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35b0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
35c0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
35d0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
35e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
35f0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3600: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3610: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3620: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3630: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3640: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3650: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3660: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3670: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3680: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3690: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
36a0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
36b0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
36c0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
36d0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
36e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36f0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
3700: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
3710: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
3720: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3730: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
3740: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
3750: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
3760: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3770: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
3780: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
3790: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
37a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
37d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
37e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
37f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
3800: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3810: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
3820: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
3830: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3840: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
3850: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
3860: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
3870: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
3880: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73  * KEYWORDS: {res
3890: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c  ult code} {resul
38a0: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d  t codes}.**.** M
38b0: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
38c0: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
38d0: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
38e0: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
38f0: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
3900: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
3910: 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66  tes success or f
3920: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
3930: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
3940: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
3950: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
3960: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
3970: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
3980: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
3990: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
39a0: 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  des].*/.#define 
39b0: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
39c0: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
39d0: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
39e0: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
39f0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
3a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
3a10: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
3a20: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
3a30: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
3a40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3a50: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
3a60: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
3a70: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
3a80: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
3a90: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
3aa0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
3ab0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
3ac0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
3ad0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
3ae0: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
3af0: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
3b00: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
3b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3b20: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
3b30: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
3b40: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
3b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3b60: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
3b70: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
3b80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
3b90: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
3ba0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
3bb0: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
3bc0: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
3bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3be0: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
3bf0: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
3c00: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
3c10: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
3c20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
3c30: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
3c40: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
3c50: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
3c60: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
3c70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
3c80: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
3c90: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
3ca0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
3cb0: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
3cc0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
3cd0: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
3ce0: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
3cf0: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
3d00: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3d10: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
3d20: 31 32 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44  12   /* NOT USED
3d30: 2e 20 54 61 62 6c 65 20 6f 72 20 72 65 63 6f 72  . Table or recor
3d40: 64 20 6e 6f 74 20 66 6f 75 6e 64 20 2a 2f 0a 23  d not found */.#
3d50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
3d60: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f  LL        13   /
3d70: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  * Insertion fail
3d80: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62  ed because datab
3d90: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23  ase is full */.#
3da0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
3db0: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f  NTOPEN    14   /
3dc0: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e  * Unable to open
3dd0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
3de0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
3df0: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20  LITE_PROTOCOL   
3e00: 20 31 35 20 20 20 2f 2a 20 4e 4f 54 20 55 53 45   15   /* NOT USE
3e10: 44 2e 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  D. Database lock
3e20: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
3e30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3e40: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
3e50: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
3e60: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
3e70: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
3e80: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
3e90: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
3ea0: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
3eb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
3ec0: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
3ed0: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
3ee0: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
3ef0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
3f00: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
3f10: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
3f20: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
3f30: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
3f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
3f50: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
3f60: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
3f70: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
3f80: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
3f90: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
3fa0: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
3fb0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
3fc0: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
3fd0: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
3fe0: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
3ff0: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4010: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
4020: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
4030: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
4040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
4050: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
4060: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4070: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4080: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4090: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
40a0: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
40b0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
40c0: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
40d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
40e0: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
40f0: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4100: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
4110: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
4120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4130: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
4140: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4150: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
4160: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4180: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4190: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
41a0: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
41b0: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
41c0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
41d0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
41e0: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
41f0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4200: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
4210: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
4220: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
4230: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
4240: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4250: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4260: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4270: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4280: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4290: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
42a0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
42b0: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
42c0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
42d0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
42e0: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
42f0: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4300: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
4310: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
4320: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
4330: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
4340: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
4350: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
4360: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4370: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4380: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4390: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
43a0: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
43b0: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
43c0: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
43d0: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
43e0: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
43f0: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4400: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
4410: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
4420: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
4430: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
4440: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
4450: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4460: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4470: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4480: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4490: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
44a0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
44b0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
44c0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
44d0: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
44e0: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
44f0: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4500: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
4510: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
4520: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
4530: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
4540: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4550: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
4560: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4570: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4580: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4590: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
45a0: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
45b0: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
45c0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
45d0: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
45e0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
45f0: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4600: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4610: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4620: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4630: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4640: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4650: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4660: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4670: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4680: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4690: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
46a0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
46b0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
46c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
46d0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
46e0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
46f0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4700: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4710: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4720: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4730: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4740: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4750: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4760: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4770: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4780: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4790: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
47a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
47b0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
47c0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
47d0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
47e0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
47f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4800: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4810: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4820: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4830: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4840: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4850: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4860: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4870: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4880: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4890: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
48a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
48b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
48c0: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
48d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
48e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
48f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4900: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4910: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4920: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4930: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4940: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4950: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4960: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4970: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4980: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4990: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
49a0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
49b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
49c0: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
49d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
49e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
49f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4a00: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4a10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4a20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4a30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4a40: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4a50: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4a60: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4a70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4a80: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4a90: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4aa0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 28 31 3c 3c  TE_LOCKED | (1<<
4ab0: 38 29 20 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  8) )../*.** CAPI
4ac0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
4ad0: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
4ae0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
4af0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
4b00: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
4b10: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
4b20: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
4b30: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
4b40: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
4b50: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
4b60: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
4b70: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
4b80: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4b90: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
4ba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4bb0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
4bc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
4bd0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4be0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4bf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c00: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
4c10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
4c20: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4c30: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c50: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
4c60: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
4c70: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4c80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ca0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
4cb0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
4cc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ce0: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
4cf0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
4d00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4d10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d20: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
4d30: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
4d40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d60: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
4d70: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
4d80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4d90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4da0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
4db0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
4dc0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4dd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4de0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
4df0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
4e00: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4e10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4e20: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
4e30: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
4e40: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4e50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4e60: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
4e70: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
4e80: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4e90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ea0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
4eb0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
4ec0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
4ed0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ee0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
4ef0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
4f00: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4f10: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f30: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
4f40: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
4f50: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4f60: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4f70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f80: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
4f90: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
4fa0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
4fb0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
4fc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4fd0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
4fe0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
4ff0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5000: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5010: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5020: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
5030: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
5040: 68 65 20 78 44 65 76 69 63 65 43 61 70 61 62 69  he xDeviceCapabi
5050: 6c 69 74 69 65 73 20 6d 65 74 68 6f 64 20 6f 66  lities method of
5060: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5070: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
5080: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
5090: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
50a0: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20  a vector of the 
50b0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
50c0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
50d0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
50e0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
50f0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
5100: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
5110: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
5120: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5130: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
5140: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
5150: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
5160: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
5170: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
5180: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
5190: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
51a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
51b0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
51c0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
51d0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
51e0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
51f0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
5200: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
5210: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
5220: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
5230: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
5240: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
5250: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5260: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
5270: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
5280: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
5290: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
52a0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
52b0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
52c0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
52d0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
52e0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
52f0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
5300: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5310: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
5320: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
5330: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
5340: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
5350: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
5360: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
5370: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f   to xWrite()..*/
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20  IOCAP_ATOMIC    
53a0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
53b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
53d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
53e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
5400: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5410: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5420: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
5430: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5450: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
5460: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5480: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
5490: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
54a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
54c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
54d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
54f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30        0x00000080
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5510: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20  IOCAP_ATOMIC64K 
5520: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5540: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
5550: 44 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30  D     0x00000200
5560: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5570: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
5580: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30        0x00000400
5590: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
55a0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
55b0: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
55c0: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
55d0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
55e0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
55f0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
5600: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
5610: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
5620: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
5630: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
5640: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5650: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5670: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
5680: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5690: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
56a0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
56b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
56c0: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
56d0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
56e0: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
56f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
5700: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
5710: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
5720: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
5730: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
5740: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
5750: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
5760: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
5770: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
5790: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
57a0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
57b0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
57c0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
57d0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
57e0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
57f0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
5800: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
5810: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
5820: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
5830: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
5840: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
5850: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
5860: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
5870: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
5880: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
5890: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
58a0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
58b0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
58c0: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
58d0: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
58e0: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
58f0: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
5900: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
5910: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
5920: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
5930: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
5940: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
5950: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
5960: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
5970: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
5980: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
5990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
59a0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
59b0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
59c0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
59d0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
59e0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
59f0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
5a00: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
5a10: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
5a20: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
5a30: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
5a40: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
5a50: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
5a60: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
5a70: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
5a80: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
5a90: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
5aa0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
5ab0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
5ac0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
5ad0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
5ae0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
5af0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
5b00: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
5b10: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
5b20: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
5b30: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
5b40: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
5b50: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
5b60: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
5b70: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
5b80: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
5b90: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
5ba0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
5bb0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
5bc0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
5bd0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
5be0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5bf0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
5c00: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
5c10: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
5c20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5c30: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
5c40: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
5c50: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
5c60: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
5c70: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
5c80: 33 5f 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74  3_vfs] xOpen met
5c90: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
5ca0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
5cb0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
5cc0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
5cd0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
5ce0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
5cf0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
5d00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
5d10: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
5d20: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
5d30: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
5d40: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
5d50: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
5d60: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
5d70: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
5d80: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
5d90: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
5da0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
5db0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f  .**.** If the xO
5dc0: 70 65 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20  pen method sets 
5dd0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
5de0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
5df0: 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e  t .** to a non-N
5e00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
5e10: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f  n the sqlite3_io
5e20: 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20  _methods.xClose 
5e30: 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65  method.** may be
5e40: 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66   invoked even if
5e50: 20 74 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72   the xOpen repor
5e60: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
5e70: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
5e80: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
5e90: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
5ea0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
5eb0: 6c 65 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20  led xOpen.** is 
5ec0: 66 6f 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f  for the xOpen to
5ed0: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
5ee0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
5ef0: 6c 65 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a  lement to NULL..
5f00: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
5f10: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
5f20: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
5f30: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
5f40: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
5f50: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
5f60: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
5f70: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
5f80: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
5f90: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
5fa0: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
5fb0: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
5fc0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
5fd0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
5fe0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
5ff0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
6000: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
6010: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
6020: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
6030: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
6040: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
6050: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
6060: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
6070: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
6080: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
6090: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
60a0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
60b0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
60c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
60d0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
60e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
60f0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
6100: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
6110: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6120: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
6130: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
6140: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
6150: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
6160: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
6170: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
6180: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
6190: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
61a0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
61b0: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
61c0: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
61d0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
61e0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
61f0: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
6200: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
6210: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
6220: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
6230: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
6240: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
6250: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
6260: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
6270: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
6280: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
6290: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
62a0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
62b0: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
62c0: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
62d0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
62e0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
62f0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
6300: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
6310: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
6320: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
6330: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
6340: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
6350: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
6360: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
6370: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
6380: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
6390: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
63a0: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
63b0: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
63c0: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
63d0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
63e0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
63f0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
6400: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
6410: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
6420: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
6430: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
6440: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
6450: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
6460: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
6470: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
6480: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
6490: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
64a0: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
64b0: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
64c0: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
64d0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
64e0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
64f0: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
6500: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
6510: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51  wn use..** A [SQ
6520: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
6530: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
6540: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
6550: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
6560: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
6570: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
6580: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
6590: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
65a0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
65b0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
65c0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
65d0: 66 6c 69 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  flicts..**.** Th
65e0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
65f0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
6600: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
6610: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
6620: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
6630: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
6640: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
6650: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
6660: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
6670: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
6680: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
6690: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
66a0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
66b0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
66c0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
66d0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
66e0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
66f0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
6700: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
6710: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
6720: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6730: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
6740: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
6750: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
6760: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6770: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
6780: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6790: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
67a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
67b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
67c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
67d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
67e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
67f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
6800: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6810: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
6820: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
6830: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
6840: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
6850: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
6860: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
6870: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6880: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
6890: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
68a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
68b0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
68c0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
68d0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
68e0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
68f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6900: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
6910: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6920: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6930: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6940: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6950: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6960: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
6970: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
6980: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
6990: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
69a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
69b0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
69c0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
69d0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
69e0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
69f0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6a00: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
6a10: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6a20: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6a30: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6a40: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6a50: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6a60: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6a70: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6a80: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
6a90: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
6aa0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
6ab0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
6ac0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
6ad0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
6ae0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
6af0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
6b00: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
6b10: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
6b20: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
6b30: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
6b40: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
6b50: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
6b60: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
6b70: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
6b80: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
6b90: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
6ba0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
6bb0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
6bc0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
6bd0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
6be0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
6bf0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
6c00: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
6c10: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
6c20: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
6c30: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
6c40: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
6c50: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
6c60: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
6c70: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
6c80: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
6c90: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
6ca0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
6cb0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
6cc0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
6cd0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
6ce0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
6cf0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
6d00: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
6d10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
6d20: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
6d30: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
6d40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
6d50: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
6d60: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
6d70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
6d80: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
6d90: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
6da0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
6db0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
6dc0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
6dd0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
6de0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
6df0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
6e00: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
6e10: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
6e20: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
6e30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
6e40: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
6e50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
6e60: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
6e70: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
6e80: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
6e90: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
6ea0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 41 64 64  file*);.  /* Add
6eb0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
6ec0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
6ed0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
6ee0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6ef0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
6f00: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
6f10: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
6f20: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
6f30: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
6f40: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
6f50: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
6f60: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6f70: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6f80: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
6f90: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
6fa0: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
6fb0: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
6fc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
6fd0: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
6fe0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
6ff0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
7000: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
7010: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7020: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
7030: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
7040: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
7050: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
7060: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
7070: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7080: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
7090: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
70a0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
70b0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
70c0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
70d0: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
70e0: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
70f0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
7100: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
7110: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
7120: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
7130: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
7140: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
7150: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
7160: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 23  is defined..*/.#
7170: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
7180: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
7190: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
71a0: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
71b0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32 0a 23  OXYFILE      2.#
71c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
71d0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
71e0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
71f0: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
7200: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 0a               4..
7210: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7220: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
7230: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
7240: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
7250: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
7260: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
7270: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
7280: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
7290: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
72a0: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
72b0: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
72c0: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
72d0: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
72e0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
72f0: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
7300: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
7310: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
7320: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
7330: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
7340: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
7350: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
7360: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
7370: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7380: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
7390: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
73a0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
73b0: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
73c0: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
73d0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
73e0: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
73f0: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
7400: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
7410: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
7420: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
7430: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
7440: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
7450: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
7460: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
7470: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
7480: 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tem"..**.** The 
7490: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
74a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
74b0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
74c0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
74d0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
74e0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
74f0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
7500: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
7510: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
7520: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
7530: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
7540: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
7550: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
7560: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
7570: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
7580: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
7590: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
75a0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
75b0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
75c0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
75d0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
75e0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
75f0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
7600: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
7610: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
7620: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
7630: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
7640: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
7650: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
7660: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
7670: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
7680: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
7690: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
76a0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
76b0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
76c0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
76d0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
76e0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
76f0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
7700: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
7710: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
7720: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
7730: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
7740: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
7750: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
7760: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
7770: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
7780: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
7790: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
77a0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
77b0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
77c0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
77d0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
77e0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
77f0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
7800: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
7810: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
7820: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
7830: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
7840: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
7850: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
7860: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
7870: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
7880: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
7890: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
78a0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
78b0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
78c0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
78d0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
78e0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
78f0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
7900: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
7910: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
7920: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
7930: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
7940: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
7950: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
7960: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
7970: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
7980: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
7990: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
79a0: 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  s..**.** SQLite 
79b0: 77 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74  will guarantee t
79c0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
79d0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
79e0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
79f0: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
7a00: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
7a10: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
7a20: 6c 50 61 74 68 6e 61 6d 65 28 29 2e 20 20 53 51  lPathname().  SQ
7a30: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
7a40: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
7a50: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
7a60: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
7a70: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
7a80: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
7a90: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
7aa0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
7ab0: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
7ac0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
7ad0: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
7ae0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
7af0: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
7b00: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
7b10: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
7b20: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
7b30: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
7b40: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
7b50: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
7b60: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
7b70: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
7b80: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
7b90: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
7ba0: 65 20 66 69 6c 65 2e 20 20 57 68 65 6e 65 76 65  e file.  Wheneve
7bb0: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
7bc0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
7bd0: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
7be0: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
7bf0: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
7c00: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
7c10: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
7c20: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
7c30: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
7c40: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
7c50: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
7c60: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
7c70: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
7c80: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
7c90: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
7ca0: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
7cb0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
7cc0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
7cd0: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
7ce0: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
7cf0: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
7d00: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
7d10: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
7d20: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
7d30: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
7d40: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
7d50: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
7d60: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
7d70: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
7d80: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
7d90: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
7da0: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
7db0: 65 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  et..**.** SQLite
7dc0: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
7dd0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
7de0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
7df0: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
7e00: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
7e10: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
7e20: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
7e30: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
7e40: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
7e50: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
7e60: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
7e70: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
7e80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
7e90: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
7ea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
7eb0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
7ec0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
7ed0: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
7ee0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
7ef0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
7f00: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
7f10: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
7f20: 4e 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  NAL].** </ul>.**
7f30: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
7f40: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
7f50: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
7f60: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
7f70: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
7f80: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
7f90: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
7fa0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
7fb0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
7fc0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
7fd0: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
7fe0: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
7ff0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
8000: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
8010: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
8020: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
8030: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
8040: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
8050: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
8060: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
8070: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
8080: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
8090: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
80a0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
80b0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
80c0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
80d0: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
80e0: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
80f0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
8100: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
8110: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
8120: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
8130: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
8140: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
8150: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
8160: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
8170: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
8180: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
8190: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
81b0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
81c0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
81d0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
81e0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
81f0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8200: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
8210: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8220: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
8230: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
8240: 63 6c 6f 73 65 64 2e 20 20 54 68 65 20 5b 53 51  closed.  The [SQ
8250: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
8260: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
8270: 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
8280: 20 20 64 61 74 61 62 61 73 65 73 2c 20 6a 6f 75    databases, jou
8290: 72 6e 61 6c 73 20 61 6e 64 20 66 6f 72 20 73 75  rnals and for su
82a0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
82b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
82c0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
82d0: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
82e0: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
82f0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
8300: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
8310: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
8320: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
8330: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
8340: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
8350: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
8360: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
8370: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
8380: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8390: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
83a0: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
83b0: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
83c0: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
83d0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
83e0: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
83f0: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
8400: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
8410: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
8420: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
8430: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
8440: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
8450: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
8460: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
8470: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
8480: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 41 74  access..**.** At
8490: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
84a0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
84b0: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
84c0: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
84d0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
84e0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
84f0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
8500: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
8510: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
8520: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
8530: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
8540: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
8550: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
8560: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
8570: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
8580: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
8590: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
85a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
85b0: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
85c0: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
85d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
85e0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
85f0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
8600: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
8610: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
8620: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
8630: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
8640: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
8650: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
8660: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
8670: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
8680: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
8690: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
86a0: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
86b0: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54  en call..**.** T
86c0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
86d0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
86e0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
86f0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
8700: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
8710: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
8720: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
8730: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
8740: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
8750: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
8760: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
8770: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
8780: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
8790: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
87a0: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
87b0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
87c0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
87d0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
87e0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
87f0: 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
8800: 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
8810: 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
8820: 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
8830: 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
8840: 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
8850: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
8860: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
8870: 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
8880: 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
8890: 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
88a0: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
88b0: 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
88c0: 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
88d0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
88e0: 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
88f0: 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
8900: 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
8910: 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
8920: 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
8930: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
8940: 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
8950: 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
8960: 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
8970: 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
8980: 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
8990: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
89a0: 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
89b0: 70 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  p(), and xCurren
89c0: 74 54 69 6d 65 28 29 20 69 6e 74 65 72 66 61 63  tTime() interfac
89d0: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 73 74  es.** are not st
89e0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
89f0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
8a00: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
8a10: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
8a20: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
8a30: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
8a40: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
8a50: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
8a60: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
8a70: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
8a80: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
8a90: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
8aa0: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
8ab0: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
8ac0: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
8ad0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
8ae0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
8af0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
8b00: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
8b10: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
8b20: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
8b30: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
8b40: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
8b50: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
8b60: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
8b70: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
8b80: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
8b90: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
8ba0: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
8bb0: 64 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2f 0a 74 79  d time..**.*/.ty
8bc0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8bd0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
8be0: 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  _vfs;.struct sql
8bf0: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
8c00: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
8c10: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
8c20: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
8c30: 72 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  r */.  int szOsF
8c40: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
8c50: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
8c60: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
8c70: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
8c80: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
8c90: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
8ca0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
8cb0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
8cc0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
8cd0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
8ce0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
8cf0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
8d00: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
8d10: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
8d20: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
8d30: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
8d40: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
8d50: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
8d60: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
8d70: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
8d80: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
8d90: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
8da0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
8db0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
8dc0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
8dd0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
8de0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
8df0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
8e00: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
8e10: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
8e20: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
8e30: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
8e40: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
8e50: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
8e60: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8e70: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
8e80: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
8e90: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
8ea0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
8eb0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
8ec0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
8ed0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
8ee0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
8ef0: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
8f00: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8f10: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
8f20: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
8f30: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
8f40: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
8f50: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
8f60: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
8f70: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
8f80: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
8f90: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
8fa0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
8fb0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
8fc0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
8fd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
8fe0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
8ff0: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
9000: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
9010: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
9020: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
9030: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
9040: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
9050: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
9060: 20 2a 29 3b 0a 20 20 2f 2a 20 4e 65 77 20 66 69   *);.  /* New fi
9070: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
9080: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
9090: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
90a0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
90b0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
90c0: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
90d0: 61 70 70 65 6e 73 2e 20 2a 2f 0a 7d 3b 0a 0a 2f  appens. */.};../
90e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
90f0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63  lags for the xAc
9100: 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a  cess VFS method.
9110: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
9120: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61  ger constants ca
9130: 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65  n be used as the
9140: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
9150: 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65   to.** the xAcce
9160: 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20  ss method of an 
9170: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
9180: 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65  ject.  They dete
9190: 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69  rmine.** what ki
91a0: 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e  nd of permission
91b0: 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  s the xAccess me
91c0: 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20  thod is looking 
91d0: 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  for..** With SQL
91e0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
91f0: 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  S, the xAccess m
9200: 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20  ethod.** simply 
9210: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
9220: 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a  he file exists..
9230: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
9240: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c  CCESS_READWRITE,
9250: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
9260: 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68  hod.** checks wh
9270: 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69  ether the file i
9280: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
9290: 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a 2a  and writable..**
92a0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
92b0: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
92c0: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
92d0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
92e0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
92f0: 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ble..*/.#define 
9300: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
9310: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
9320: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
9330: 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65 66  READWRITE 1.#def
9340: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
9350: 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a 2f  S_READ      2../
9360: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
9370: 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51  nitialize The SQ
9380: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
9390: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
93a0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
93b0: 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73  tine initializes
93c0: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c   the.** SQLite l
93d0: 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71  ibrary.  ^The sq
93e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
93f0: 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c   routine.** deal
9400: 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f  locates any reso
9410: 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20  urces that were 
9420: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
9430: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9440: 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  )..** These rout
9450: 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65  ines are designe
9460: 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63  d to aid in proc
9470: 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
9480: 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f  on and.** shutdo
9490: 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73  wn on embedded s
94a0: 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61  ystems.  Worksta
94b0: 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  tion application
94c0: 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74  s using.** SQLit
94d0: 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f  e normally do no
94e0: 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65  t need to invoke
94f0: 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65   either of these
9500: 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
9510: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
9520: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9530: 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
9540: 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a  " call if it is.
9550: 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  ** the first tim
9560: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9570: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
9580: 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66  d during the lif
9590: 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20  etime of.** the 
95a0: 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69  process, or if i
95b0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74  t is the first t
95c0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
95d0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
95e0: 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  ked.** following
95f0: 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   a call to sqlit
9600: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
9610: 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74  ^(Only an effect
9620: 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73  ive call.** of s
9630: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9640: 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69  e() does any ini
9650: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c  tialization.  Al
9660: 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a  l other calls.**
9670: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
9680: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  -ops.)^.**.** A 
9690: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
96a0: 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e  shutdown() is an
96b0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
96c0: 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  l if it is the f
96d0: 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  irst.** call to 
96e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
96f0: 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73  () since the las
9700: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
9710: 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a  lize().  ^(Only.
9720: 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ** an effective 
9730: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
9740: 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20  shutdown() does 
9750: 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61  any deinitializa
9760: 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68  tion..** All oth
9770: 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74  er valid calls t
9780: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
9790: 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73  wn() are harmles
97a0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
97b0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
97c0: 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72  itialize() inter
97d0: 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61  face is threadsa
97e0: 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f  fe, but sqlite3_
97f0: 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73  shutdown().** is
9800: 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74   not.  The sqlit
9810: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e  e3_shutdown() in
9820: 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c  terface must onl
9830: 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  y be called from
9840: 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72   a.** single thr
9850: 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b  ead.  All open [
9860: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9870: 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c  ions] must be cl
9880: 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20  osed and all.** 
9890: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73  other SQLite res
98a0: 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64  ources must be d
98b0: 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72  eallocated prior
98c0: 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   to invoking.** 
98d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
98e0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20  ()..**.** Among 
98f0: 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73  other things, ^s
9900: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9910: 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  e() will invoke.
9920: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
9930: 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79  it().  Similarly
9940: 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64  , ^sqlite3_shutd
9950: 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e  own().** will in
9960: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f  voke sqlite3_os_
9970: 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  end()..**.** ^Th
9980: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
9990: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72  lize() routine r
99a0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
99b0: 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a  K] on success..*
99c0: 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72  * ^If for some r
99d0: 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69  eason, sqlite3_i
99e0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75  nitialize() is u
99f0: 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c  nable to initial
9a00: 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61  ize.** the libra
9a10: 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69  ry (perhaps it i
9a20: 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
9a30: 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65  cate a needed re
9a40: 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61  source such.** a
9a50: 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65  s a mutex) it re
9a60: 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20  turns an [error 
9a70: 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e  code] other than
9a80: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
9a90: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
9aa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
9ab0: 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
9ac0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61  internally by ma
9ad0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ny other.** SQLi
9ae0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f  te interfaces so
9af0: 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61   that an applica
9b00: 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65  tion usually doe
9b10: 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a  s not need to.**
9b20: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
9b30: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72  initialize() dir
9b40: 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d  ectly.  For exam
9b50: 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ple, [sqlite3_op
9b60: 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73  en()].** calls s
9b70: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9b80: 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74  e() so the SQLit
9b90: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62  e library will b
9ba0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
9bb0: 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77  ** initialized w
9bc0: 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  hen [sqlite3_ope
9bd0: 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69  n()] is called i
9be0: 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20  f it has not be 
9bf0: 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61  initialized.** a
9c00: 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65  lready.  ^Howeve
9c10: 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  r, if SQLite is 
9c20: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
9c30: 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
9c40: 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70  UTOINIT].** comp
9c50: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c  ile-time option,
9c60: 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61   then the automa
9c70: 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  tic calls to sql
9c80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9c90: 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64  ).** are omitted
9ca0: 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
9cb0: 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73  tion must call s
9cc0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9cd0: 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  e() directly.** 
9ce0: 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
9cf0: 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
9d00: 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20  interface.  For 
9d10: 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c  maximum portabil
9d20: 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65  ity,.** it is re
9d30: 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
9d40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61  pplications alwa
9d50: 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ys invoke sqlite
9d60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
9d70: 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72  * directly prior
9d80: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
9d90: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
9da0: 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65  face.  Future re
9db0: 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c  leases.** of SQL
9dc0: 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20  ite may require 
9dd0: 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20  this.  In other 
9de0: 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76  words, the behav
9df0: 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a  ior exhibited.**
9e00: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
9e10: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
9e20: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
9e30: 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d  NIT] might becom
9e40: 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74  e the.** default
9e50: 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d   behavior in som
9e60: 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
9e70: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
9e80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73  * The sqlite3_os
9e90: 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20  _init() routine 
9ea0: 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73  does operating-s
9eb0: 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a  ystem specific.*
9ec0: 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  * initialization
9ed0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c   of the SQLite l
9ee0: 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c  ibrary.  The sql
9ef0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
9f00: 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20   routine undoes 
9f10: 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71  the effect of sq
9f20: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
9f30: 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a    Typical tasks.
9f40: 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20  ** performed by 
9f50: 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69  these routines i
9f60: 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f  nclude allocatio
9f70: 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f  n or deallocatio
9f80: 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72  n.** of static r
9f90: 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61  esources, initia
9fa0: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62  lization of glob
9fb0: 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a  al variables,.**
9fc0: 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65   setting up a de
9fd0: 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
9fe0: 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73  fs] module, or s
9ff0: 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64  etting up.** a d
a000: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
a010: 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69  tion using [sqli
a020: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a  te3_config()]..*
a030: 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
a040: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
a050: 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  r invoke either 
a060: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a070: 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
a080: 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c  os_end() directl
a090: 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  y.  The applicat
a0a0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20  ion should only 
a0b0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
a0c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
a0d0: 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nd sqlite3_shutd
a0e0: 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69  own().  The sqli
a0f0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
a100: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61   interface is ca
a110: 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  lled automatical
a120: 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ly by sqlite3_in
a130: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a  itialize() and.*
a140: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  * sqlite3_os_end
a150: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20  () is called by 
a160: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a170: 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65  ().  Appropriate
a180: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
a190: 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ons for sqlite3_
a1a0: 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
a1b0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
a1c0: 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f  * are built into
a1d0: 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20   SQLite when it 
a1e0: 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
a1f0: 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f  Unix, Windows, o
a200: 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20  r OS/2..** When 
a210: 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c  [custom builds |
a220: 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72   built for other
a230: 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28   platforms].** (
a240: 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
a250: 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f  E_OS_OTHER=1] co
a260: 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
a270: 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63  tion) the applic
a280: 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c  ation must suppl
a290: 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70  y a suitable imp
a2a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  lementation for.
a2b0: 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  ** sqlite3_os_in
a2c0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
a2d0: 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61  _os_end().  An a
a2e0: 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c  pplication-suppl
a2f0: 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ied.** implement
a300: 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
a310: 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71  _os_init() or sq
a320: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
a330: 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53  * must return [S
a340: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
a350: 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74  cess and some ot
a360: 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  her [error code]
a370: 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65   upon.** failure
a380: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
a390: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
a3a0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  );.int sqlite3_s
a3b0: 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69  hutdown(void);.i
a3c0: 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  nt sqlite3_os_in
a3d0: 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  it(void);.int sq
a3e0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69  lite3_os_end(voi
a3f0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
a400: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67  REF: Configuring
a410: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
a420: 61 72 79 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ary.** EXPERIMEN
a430: 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  TAL.**.** The sq
a440: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
a450: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
a460: 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20   to make global 
a470: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
a480: 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69   changes to SQLi
a490: 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74  te in order to t
a4a0: 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68  une SQLite to th
a4b0: 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
a4c0: 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
a4d0: 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66  cation.  The def
a4e0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
a4f0: 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  on is recommende
a500: 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70  d for most.** ap
a510: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73  plications and s
a520: 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  o this routine i
a530: 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65  s usually not ne
a540: 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a  cessary.  It is.
a550: 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  ** provided to s
a560: 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c  upport rare appl
a570: 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e  ications with un
a580: 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a  usual needs..**.
a590: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
a5a0: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
a5b0: 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  e is not threads
a5c0: 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63  afe.  The applic
a5d0: 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  ation.** must in
a5e0: 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68  sure that no oth
a5f0: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
a600: 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64  aces are invoked
a610: 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72   by other.** thr
a620: 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74  eads while sqlit
a630: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72  e3_config() is r
a640: 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72  unning.  Further
a650: 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f  more, sqlite3_co
a660: 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e  nfig().** may on
a670: 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
a680: 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
a690: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
a6a0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
a6b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
a6c0: 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
a6d0: 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
a6e0: 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
a6f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
a700: 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
a710: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
a720: 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
a730: 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
a740: 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
a750: 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
a760: 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
a770: 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
a780: 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
a790: 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
a7a0: 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
a7b0: 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
a7c0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
a7d0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
a7e0: 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
a7f0: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
a800: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
a810: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a820: 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
a830: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
a840: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c  G_SINGLETHREAD |
a850: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
a860: 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
a870: 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
a880: 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
a890: 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
a8a0: 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
a8b0: 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
a8c0: 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
a8d0: 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  n the [SQLITE_CO
a8e0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
a8f0: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
a900: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
a910: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
a920: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
a930: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
a940: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
a950: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
a960: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a970: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
a980: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
a990: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
a9a0: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
a9b0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
a9c0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
a9d0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
a9e0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
a9f0: 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
aa00: 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33  NTAL int sqlite3
aa10: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
aa20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
aa30: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
aa40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
aa50: 6e 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ns.** EXPERIMENT
aa60: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  AL.**.** The sql
aa70: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
aa80: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
aa90: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
aaa0: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
aab0: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
aac0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
aad0: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
aae0: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
aaf0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
ab00: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
ab10: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
ab20: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
ab30: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ab40: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
ab50: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
ab60: 67 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a  gument).  The.**
ab70: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
ab80: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ig() interface s
ab90: 68 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73  hould only be us
aba0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  ed immediately a
abb0: 66 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61  fter.** the data
abc0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
abd0: 69 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  is created using
abe0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
abf0: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
ac00: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71  pen16()], or [sq
ac10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
ac20: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .  .**.** The se
ac30: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
ac40: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
ac50: 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
ac60: 74 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  the.** configura
ac70: 74 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69  tion verb - an i
ac80: 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
ac90: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a   indicates what.
aca0: 2a 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  ** aspect of the
acb0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
acc0: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
acd0: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54  configured..** T
ace0: 68 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66  he only choice f
acf0: 6f 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73  or this value is
ad00: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
ad10: 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a  G_LOOKASIDE]..**
ad20: 20 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c   New verbs are l
ad30: 69 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65  ikely to be adde
ad40: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
ad50: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
ad60: 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72  ** Additional ar
ad70: 67 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f  guments depend o
ad80: 6e 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a  n the verb..**.*
ad90: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
ada0: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
adb0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
adc0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
add0: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
ade0: 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
adf0: 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  sful..*/.SQLITE_
ae00: 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74  EXPERIMENTAL int
ae10: 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
ae20: 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ig(sqlite3*, int
ae30: 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a   op, ...);../*.*
ae40: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
ae50: 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f  ry Allocation Ro
ae60: 75 74 69 6e 65 73 0a 2a 2a 20 45 58 50 45 52 49  utines.** EXPERI
ae70: 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20  MENTAL.**.** An 
ae80: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
ae90: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
aea0: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
aeb0: 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20  tween SQLite.** 
aec0: 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  and low-level me
aed0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
aee0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
aef0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75  This object is u
af00: 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20  sed in only one 
af10: 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c  place in the SQL
af20: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
af30: 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * A pointer to a
af40: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
af50: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65  is object is the
af60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
af70: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
af80: 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66  )] when the conf
af90: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
afa0: 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43   is.** [SQLITE_C
afb0: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72  ONFIG_MALLOC] or
afc0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
afd0: 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a  GETMALLOC].  .**
afe0: 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20   By creating an 
aff0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
b000: 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70   object.** and p
b010: 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
b020: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
b030: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
b040: 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20  LOC]).** during 
b050: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61  configuration, a
b060: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61  n application ca
b070: 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  n specify an alt
b080: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
b090: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
b0a0: 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69  bsystem for SQLi
b0b0: 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c  te to use for al
b0c0: 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61  l of its.** dyna
b0d0: 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  mic memory needs
b0e0: 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
b0f0: 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77  t SQLite comes w
b100: 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69  ith several [bui
b110: 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
b120: 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74  ocators].** that
b130: 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61   are perfectly a
b140: 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20  dequate for the 
b150: 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a  overwhelming maj
b160: 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
b170: 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61  tions.** and tha
b180: 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  t this object is
b190: 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20   only useful to 
b1a0: 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20  a tiny minority 
b1b0: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
b1c0: 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69  ** with speciali
b1d0: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
b1e0: 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e  ation requiremen
b1f0: 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ts.  This object
b200: 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64   is.** also used
b210: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
b220: 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  of SQLite in ord
b230: 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e  er to specify an
b240: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
b250: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
b260: 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20   that simulates 
b270: 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65  memory out-of-me
b280: 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20  mory conditions 
b290: 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76  in.** order to v
b2a0: 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74  erify that SQLit
b2b0: 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65  e recovers grace
b2c0: 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a  fully from such.
b2d0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a  ** conditions..*
b2e0: 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63  *.** The xMalloc
b2f0: 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
b300: 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
b310: 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
b320: 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
b330: 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
b340: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
b350: 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c  ry..** The xReal
b360: 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  loc method must 
b370: 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f  work like reallo
b380: 63 28 29 20 66 72 6f 6d 20 74 68 65 20 73 74 61  c() from the sta
b390: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 0a  ndard C library.
b3a0: 2a 2a 20 77 69 74 68 20 74 68 65 20 65 78 63 65  ** with the exce
b3b0: 70 74 69 6f 6e 20 74 68 61 74 20 69 66 20 74 68  ption that if th
b3c0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
b3d0: 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73  t to xRealloc is
b3e0: 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c   zero,.** xReall
b3f0: 6f 63 20 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d  oc must be a no-
b400: 6f 70 20 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74  op - it must not
b410: 20 70 65 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c   perform any all
b420: 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65  ocation or.** de
b430: 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51  allocation.  ^SQ
b440: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
b450: 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20  that the second 
b460: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78  argument to.** x
b470: 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79  Realloc is alway
b480: 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e  s a value return
b490: 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61  ed by a prior ca
b4a0: 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a  ll to xRoundup..
b4b0: 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20 63 61 73  ** And so in cas
b4c0: 65 73 20 77 68 65 72 65 20 78 52 6f 75 6e 64 75  es where xRoundu
b4d0: 70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  p always returns
b4e0: 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 6d 62   a positive numb
b4f0: 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20  er,.** xRealloc 
b500: 63 61 6e 20 70 65 72 66 6f 72 6d 20 65 78 61 63  can perform exac
b510: 74 6c 79 20 61 73 20 74 68 65 20 73 74 61 6e 64  tly as the stand
b520: 61 72 64 20 6c 69 62 72 61 72 79 20 72 65 61 6c  ard library real
b530: 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69  loc() and.** sti
b540: 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61  ll be in complia
b550: 6e 63 65 20 77 69 74 68 20 74 68 69 73 20 73 70  nce with this sp
b560: 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a  ecification..**.
b570: 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
b580: 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
b590: 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
b5a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b5b0: 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
b5c0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
b5d0: 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
b5e0: 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
b5f0: 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
b600: 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
b610: 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
b620: 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
b630: 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
b640: 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
b650: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
b660: 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
b670: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
b680: 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
b690: 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
b6a0: 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
b6b0: 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
b6c0: 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
b6d0: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
b6e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b6f0: 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
b700: 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
b710: 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
b720: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
b730: 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
b740: 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
b750: 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
b760: 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
b770: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
b780: 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
b790: 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
b7a0: 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
b7b0: 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
b7c0: 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
b7d0: 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
b7e0: 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
b7f0: 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
b800: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
b810: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
b820: 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
b830: 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
b840: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
b850: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
b860: 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65  r.  (For example
b870: 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c  ,.** it might al
b880: 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69  locate any requi
b890: 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e  re mutexes or in
b8a0: 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61  itialize interna
b8b0: 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74  l data.** struct
b8c0: 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74  ures.  The xShut
b8d0: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69  down method is i
b8e0: 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74  nvoked (indirect
b8f0: 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ly) by.** [sqlit
b900: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61  e3_shutdown()] a
b910: 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f  nd should deallo
b920: 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63  cate any resourc
b930: 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62  es acquired.** b
b940: 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41  y xInit.  The pA
b950: 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69  ppData pointer i
b960: 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e  s used as the on
b970: 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  ly parameter to.
b980: 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68  ** xInit and xSh
b990: 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  utdown..**.** SQ
b9a0: 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b  Lite holds the [
b9b0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
b9c0: 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65  TIC_MASTER] mute
b9d0: 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65  x when it invoke
b9e0: 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d  s.** the xInit m
b9f0: 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49  ethod, so the xI
ba00: 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20  nit method need 
ba10: 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66  not be threadsaf
ba20: 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74  e.  The.** xShut
ba30: 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f  down method is o
ba40: 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  nly called from 
ba50: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
ba60: 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a  n()] so it does.
ba70: 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  ** not need to b
ba80: 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74  e threadsafe eit
ba90: 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74  her.  For all ot
baa0: 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c  her methods, SQL
bab0: 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65  ite.** holds the
bac0: 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53   [SQLITE_MUTEX_S
bad0: 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78  TATIC_MEM] mutex
bae0: 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a   as long as the.
baf0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
bb00: 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e  G_MEMSTATUS] con
bb10: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bb20: 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28  n is turned on (
bb30: 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62  which.** it is b
bb40: 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73  y default) and s
bb50: 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72  o the methods ar
bb60: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
bb70: 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48  serialized..** H
bb80: 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49  owever, if [SQLI
bb90: 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
bba0: 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64  TUS] is disabled
bbb0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72  , then the other
bbc0: 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  .** methods must
bbd0: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f   be threadsafe o
bbe0: 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69  r else make thei
bbf0: 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e  r own arrangemen
bc00: 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c  ts for.** serial
bc10: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  ization..**.** S
bc20: 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
bc30: 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20   invoke xInit() 
bc40: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77  more than once w
bc50: 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76  ithout an interv
bc60: 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f  ening.** call to
bc70: 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f   xShutdown()..*/
bc80: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
bc90: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
bca0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  ods sqlite3_mem_
bcb0: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
bcc0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
bcd0: 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a  ods {.  void *(*
bce0: 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20  xMalloc)(int);  
bcf0: 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79         /* Memory
bd00: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63   allocation func
bd10: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28  tion */.  void (
bd20: 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20  *xFree)(void*); 
bd30: 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65           /* Free
bd40: 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74   a prior allocat
bd50: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28  ion */.  void *(
bd60: 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a  *xRealloc)(void*
bd70: 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a  ,int);  /* Resiz
bd80: 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e an allocation 
bd90: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65  */.  int (*xSize
bda0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
bdb0: 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68      /* Return th
bdc0: 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c  e size of an all
bdd0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
bde0: 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74   (*xRoundup)(int
bdf0: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  );          /* R
be00: 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20  ound up request 
be10: 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69  size to allocati
be20: 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74  on size */.  int
be30: 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29   (*xInit)(void*)
be40: 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49  ;           /* I
be50: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
be60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
be70: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74  /.  void (*xShut
be80: 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20  down)(void*);   
be90: 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69     /* Deinitiali
bea0: 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
beb0: 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
bec0: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
bed0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
bee0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74  rgument to xInit
bef0: 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  () and xShutdown
bf00: 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  () */.};../*.** 
bf10: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
bf20: 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
bf30: 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
bf40: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
bf50: 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
bf60: 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
bf70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
bf80: 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
bf90: 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
bfa0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
bfb0: 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
bfc0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
bfd0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
bfe0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
bff0: 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
c000: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
c010: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
c020: 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
c030: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
c040: 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
c050: 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
c060: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
c070: 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
c080: 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
c090: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
c0a0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
c0b0: 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
c0c0: 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
c0d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
c0e0: 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
c0f0: 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
c100: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
c110: 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
c120: 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
c130: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
c140: 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
c150: 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
c160: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
c170: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
c180: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
c190: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
c1a0: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
c1b0: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
c1c0: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
c1d0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
c1e0: 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
c1f0: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
c200: 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
c210: 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
c220: 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
c230: 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
c240: 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
c250: 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
c260: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
c270: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
c280: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
c290: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
c2a0: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
c2b0: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
c2c0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
c2d0: 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
c2e0: 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
c2f0: 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
c300: 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
c310: 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
c320: 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
c330: 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
c340: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
c350: 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
c360: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
c370: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
c380: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
c390: 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
c3a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
c3b0: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
c3c0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
c3d0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
c3e0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
c3f0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
c400: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
c410: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
c420: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
c430: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
c440: 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
c450: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
c460: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
c470: 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
c480: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
c490: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
c4a0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
c4b0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
c4c0: 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
c4d0: 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
c4e0: 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
c4f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c500: 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
c510: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
c520: 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
c530: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
c540: 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
c550: 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
c560: 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
c570: 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
c580: 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
c590: 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
c5a0: 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
c5b0: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
c5c0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c5d0: 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
c5e0: 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
c5f0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
c600: 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
c610: 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
c620: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
c630: 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
c640: 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
c650: 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
c660: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
c670: 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
c680: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
c690: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
c6a0: 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
c6b0: 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
c6c0: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
c6d0: 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
c6e0: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
c6f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
c700: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
c710: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
c720: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f  FIG_SERIALIZED</
c730: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
c740: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
c750: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
c760: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
c770: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
c780: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
c790: 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f  Serialized. In o
c7a0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73  ther words, this
c7b0: 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a   option enables.
c7c0: 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69  ** all mutexes i
c7d0: 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63  ncluding the rec
c7e0: 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65  ursive.** mutexe
c7f0: 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
c800: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
c810: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
c820: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
c830: 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68  In this mode (wh
c840: 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75  ich is the defau
c850: 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  lt when SQLite i
c860: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
c870: 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  ** [SQLITE_THREA
c880: 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51  DSAFE=1]) the SQ
c890: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
c8a0: 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69  l itself seriali
c8b0: 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ze access.** to 
c8c0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c8d0: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
c8e0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
c8f0: 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20   so that the.** 
c900: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66  application is f
c910: 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73  ree to use the s
c920: 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
c930: 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65  nnection] or the
c940: 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72  .** same [prepar
c950: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
c960: 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
c970: 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ds at the same t
c980: 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ime..** ^If SQLi
c990: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
c9a0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
c9b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
c9c0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
c9d0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
c9e0: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
c9f0: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
ca00: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53  ble to set the S
ca10: 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
ca20: 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
ca30: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
ca40: 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
ca50: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
ca60: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
ca70: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
ca80: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63  FIG_SERIALIZED c
ca90: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
caa0: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
cab0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
cac0: 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
cad0: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
cae0: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
caf0: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
cb00: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
cb10: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
cb20: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
cb30: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
cb40: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
cb50: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
cb60: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
cb70: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
cb80: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
cb90: 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
cba0: 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
cbb0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
cbc0: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
cbd0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
cbe0: 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
cbf0: 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
cc00: 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
cc10: 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
cc20: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
cc30: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
cc40: 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
cc50: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
cc60: 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
cc70: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
cc80: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
cc90: 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
cca0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
ccb0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
ccc0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
ccd0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
cce0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
ccf0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
cd00: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
cd10: 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
cd20: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
cd30: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
cd40: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
cd50: 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
cd60: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
cd70: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
cd80: 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
cd90: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
cda0: 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
cdb0: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
cdc0: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
cdd0: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
cde0: 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
cdf0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ce00: 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
ce10: 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
ce20: 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
ce30: 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  e. </dd>.**.** <
ce40: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ce50: 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
ce60: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
ce70: 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
ce80: 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
ce90: 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
cea0: 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
ceb0: 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
cec0: 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
ced0: 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
cee0: 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
cef0: 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
cf00: 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
cf10: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
cf20: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
cf30: 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
cf40: 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
cf50: 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
cf60: 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
cf70: 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
cf80: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
cf90: 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
cfa0: 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
cfb0: 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
cfc0: 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
cfd0: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
cfe0: 70 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20  p_limit()].**   
cff0: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
d000: 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  atus()].**   </u
d010: 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
d020: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
d030: 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
d040: 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
d050: 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
d060: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
d070: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
d080: 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
d090: 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
d0a0: 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
d0b0: 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
d0c0: 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
d0d0: 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
d0e0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d0f0: 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
d100: 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
d110: 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
d120: 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
d130: 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
d140: 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
d150: 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
d160: 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
d170: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
d180: 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
d190: 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
d1a0: 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
d1b0: 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 63   which the scrac
d1c0: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
d1d0: 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
d1e0: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
d1f0: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
d200: 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
d210: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
d220: 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
d230: 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
d240: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
d250: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
d260: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68  ltiple of 16. Th
d270: 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73  e sz parameter s
d280: 68 6f 75 6c 64 20 62 65 20 61 20 66 65 77 20 62  hould be a few b
d290: 79 74 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74  ytes.** larger t
d2a0: 68 61 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73  han the actual s
d2b0: 63 72 61 74 63 68 20 73 70 61 63 65 20 72 65 71  cratch space req
d2c0: 75 69 72 65 64 20 64 75 65 20 74 6f 20 69 6e 74  uired due to int
d2d0: 65 72 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a  ernal overhead..
d2e0: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
d2f0: 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
d300: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
d310: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
d320: 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
d330: 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
d340: 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
d350: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
d360: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
d370: 72 61 74 63 68 20 62 75 66 66 65 72 20 70 65 72  ratch buffer per
d380: 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
d390: 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
d3a0: 74 6f 20 74 68 65 20 65 78 70 65 63 74 65 64 20  to the expected 
d3b0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
d3c0: 66 20 74 68 72 65 61 64 73 2e 20 20 5e 53 51 4c  f threads.  ^SQL
d3d0: 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65  ite will.** neve
d3e0: 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72 61  r require a scra
d3f0: 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20  tch buffer that 
d400: 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 20 74  is more than 6 t
d410: 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
d420: 65 0a 2a 2a 20 70 61 67 65 20 73 69 7a 65 2e 20  e.** page size. 
d430: 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
d440: 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
d450: 6c 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  l scratch memory
d460: 20 62 65 79 6f 6e 64 20 0a 2a 2a 20 77 68 61 74   beyond .** what
d470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
d480: 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
d490: 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
d4a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
d4b0: 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
d4c0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
d4d0: 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
d4e0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d4f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
d500: 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
d510: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
d520: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
d530: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
d540: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
d550: 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
d560: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
d570: 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
d580: 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
d590: 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e  e implemenation.
d5a0: 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
d5b0: 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
d5c0: 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
d5d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
d5e0: 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
d5f0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
d600: 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
d610: 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
d620: 46 49 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f  FIG_PCACHE optio
d630: 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  n..** There are 
d640: 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
d650: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20  to this option: 
d660: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62  A pointer to 8-b
d670: 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d  yte aligned.** m
d680: 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20  emory, the size 
d690: 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66  of each page buf
d6a0: 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68  fer (sz), and th
d6b0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65  e number of page
d6c0: 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a  s (N)..** The sz
d6d0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
d6e0: 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20   be the size of 
d6f0: 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61  the largest data
d700: 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20  base page.** (a 
d710: 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74  power of two bet
d720: 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37  ween 512 and 327
d730: 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c  68) plus a littl
d740: 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63 68  e extra for each
d750: 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e  .** page header.
d760: 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61 64    ^The page head
d770: 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f  er size is 20 to
d780: 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e 64   40 bytes depend
d790: 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f  ing on.** the ho
d7a0: 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65 2e  st architecture.
d7b0: 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73    ^It is harmles
d7c0: 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
d7d0: 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
d7e0: 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61  .** to make sz a
d7f0: 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67   little too larg
d800: 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a  e.  The first.**
d810: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
d820: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c   point to an all
d830: 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65  ocation of at le
d840: 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
d850: 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
d860: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
d870: 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65  e memory provide
d880: 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61  d by the first a
d890: 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73  rgument to satis
d8a0: 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79  fy its.** memory
d8b0: 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66   needs for the f
d8c0: 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61  irst N pages tha
d8d0: 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63  t it adds to cac
d8e0: 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f  he.  ^If additio
d8f0: 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  nal.** page cach
d900: 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64  e memory is need
d910: 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69  ed beyond what i
d920: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
d930: 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a  is option, then.
d940: 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74  ** SQLite goes t
d950: 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  o [sqlite3_mallo
d960: 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64  c()] for the add
d970: 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20  itional storage 
d980: 73 70 61 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  space..** ^The i
d990: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
d9a0: 67 68 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d  ght use one or m
d9b0: 6f 72 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66  ore of the N buf
d9c0: 66 65 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a  fers to hold .**
d9d0: 20 6d 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69   memory accounti
d9e0: 6e 67 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20  ng information. 
d9f0: 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  The pointer in t
da00: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
da10: 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69  t must.** be ali
da20: 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
da30: 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  e boundary or su
da40: 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
da50: 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  r of SQLite.** w
da60: 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
da70: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
da80: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
da90: 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
daa0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
dab0: 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
dac0: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
dad0: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
dae0: 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f  use.** for all o
daf0: 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
db00: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
db10: 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f  needs beyond tho
db20: 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66  se provided.** f
db30: 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
db40: 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
db50: 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d [SQLITE_CONFIG
db60: 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
db70: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
db80: 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d  arguments: An 8-
db90: 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
dba0: 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
dbb0: 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
dbc0: 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
dbd0: 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
dbe0: 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
dbf0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
dc00: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
dc10: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
dc20: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
dc30: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
dc40: 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
dc50: 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
dc60: 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
dc70: 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
dc80: 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
dc90: 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
dca0: 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
dcb0: 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
dcc0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
dcd0: 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
dce0: 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
dcf0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  r is not NULL an
dd00: 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  d either [SQLITE
dd10: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
dd20: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45   or.** [SQLITE_E
dd30: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
dd40: 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e  re defined, then
dd50: 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
dd60: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
dd70: 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
dd80: 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
dd90: 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
dda0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
ddb0: 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
ddc0: 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
ddd0: 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
dde0: 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
ddf0: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
de00: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
de10: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
de20: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
de30: 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a  defined.</dd>.**
de40: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
de50: 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
de60: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
de70: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
de80: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
de90: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
dea0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
deb0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
dec0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
ded0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
dee0: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
def0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
df00: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
df10: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
df20: 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
df30: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72  e.** the mutex r
df40: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
df50: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
df60: 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
df70: 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e  py of the.** con
df80: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
df90: 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
dfa0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
dfb0: 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
dfc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
dfd0: 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
dfe0: 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
dff0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
e000: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
e010: 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
e020: 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
e030: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
e040: 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
e050: 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
e060: 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
e070: 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
e080: 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
e090: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
e0a0: 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
e0b0: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
e0c0: 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
e0d0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
e0e0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
e0f0: 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
e100: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
e110: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
e120: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
e130: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
e140: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
e150: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
e160: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
e170: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
e180: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
e190: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
e1a0: 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  e.  The.** [sqli
e1b0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
e1c0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
e1d0: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
e1e0: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
e1f0: 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69  ined mutex routi
e200: 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
e210: 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
e220: 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
e230: 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
e240: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
e250: 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
e260: 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72  apper used to tr
e270: 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20  ack mutex usage 
e280: 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a  for performance.
e290: 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20  ** profiling or 
e2a0: 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61  testing, for exa
e2b0: 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69  mple.   ^If SQLi
e2c0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
e2d0: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
e2e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
e2f0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e300: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
e310: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
e320: 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
e330: 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
e340: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
e350: 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
e360: 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
e370: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e380: 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
e390: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
e3a0: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
e3b0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
e3c0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
e3d0: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
e3e0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e3f0: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
e400: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
e410: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
e420: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
e430: 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
e440: 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
e450: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6c 6f 6f 6b   allocation look
e460: 61 73 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69  aside optimizati
e470: 6f 6e 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  on.  The first a
e480: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
e490: 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
e4a0: 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
e4b0: 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
e4c0: 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
e4d0: 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
e4e0: 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
e4f0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e500: 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
e510: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
e520: 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
e530: 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
e540: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
e550: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
e560: 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
e570: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
e580: 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
e590: 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
e5a0: 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
e5b0: 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
e5c0: 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
e5d0: 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
e5e0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
e5f0: 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  G_PCACHE</dt>.**
e600: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
e610: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
e620: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
e630: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
e640: 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33  o.** an [sqlite3
e650: 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d  _pcache_methods]
e660: 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
e670: 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20  bject specifies 
e680: 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
e690: 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
e6a0: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
e6b0: 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69  tation.)^  ^SQLi
e6c0: 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
e6d0: 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74  of the.** object
e6e0: 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72   and uses it for
e6f0: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
e700: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c  ry allocations.<
e710: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
e720: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
e730: 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
e740: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
e750: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
e760: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
e770: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
e780: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  an.** [sqlite3_p
e790: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f  cache_methods] o
e7a0: 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
e7b0: 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72  opies of the cur
e7c0: 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63  rent.** page cac
e7d0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
e7e0: 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
e7f0: 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
e800: 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
e810: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
e820: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
e830: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
e840: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
e850: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
e860: 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
e870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
e880: 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
e890: 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
e8a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
e8b0: 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
e8c0: 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
e8d0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
e8e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
e8f0: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
e900: 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
e910: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
e920: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e930: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
e940: 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
e950: 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
e960: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
e970: 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
e980: 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
e990: 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
e9a0: 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
e9b0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
e9c0: 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
e9d0: 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
e9e0: 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
e9f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
ea00: 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
ea10: 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
ea20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ea30: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
ea40: 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
ea50: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
ea60: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
ea70: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
ea80: 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
ea90: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
eaa0: 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
eab0: 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
eac0: 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
ead0: 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
eae0: 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
eaf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
eb00: 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
eb10: 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
eb20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
eb30: 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
eb40: 20 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69       14  /* sqli
eb50: 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
eb60: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
eb70: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
eb80: 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
eb90: 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
eba0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a  methods* */../*.
ebb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
ebc0: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
ebd0: 6e 73 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ns.** EXPERIMENT
ebe0: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  AL.**.** These c
ebf0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
ec00: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
ec10: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
ec20: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
ec30: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
ec40: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
ec50: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
ec60: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
ec70: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
ec80: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
ec90: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
eca0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
ecb0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
ecc0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
ecd0: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
ece0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
ecf0: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
ed00: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
ed10: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
ed20: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
ed30: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
ed40: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
ed50: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
ed60: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
ed70: 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
ed80: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
ed90: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
eda0: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
edb0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
edc0: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
edd0: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
ede0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
edf0: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
ee00: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
ee10: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
ee20: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
ee30: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
ee40: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
ee50: 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
ee60: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
ee70: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
ee80: 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
ee90: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
eea0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
eeb0: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
eec0: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
eed0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
eee0: 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
eef0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
ef00: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
ef10: 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
ef20: 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66  to an memory buf
ef30: 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
ef40: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
ef50: 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
ef60: 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
ef70: 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
ef80: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
ef90: 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
efa0: 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
efb0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
efc0: 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
efd0: 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
efe0: 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
eff0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
f000: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f010: 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
f020: 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
f030: 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
f040: 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
f050: 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
f060: 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
f070: 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
f080: 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
f090: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
f0a0: 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
f0b0: 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
f0c0: 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
f0d0: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
f0e0: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
f0f0: 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
f100: 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
f110: 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
f120: 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
f130: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
f140: 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
f150: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
f160: 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
f170: 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
f180: 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
f190: 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
f1a0: 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d  ext smaller.** m
f1b0: 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 53  ultiple of 8.  S
f1c0: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
f1d0: 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
f1e0: 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  E]</dd>.**.** </
f1f0: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
f200: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
f210: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31  OOKASIDE    1001
f220: 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
f230: 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt */.../*.** CA
f240: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
f250: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
f260: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
f270: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
f280: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
f290: 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
f2a0: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
f2b0: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
f2c0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
f2d0: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
f2e0: 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
f2f0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
f300: 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
f310: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
f320: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
f330: 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
f340: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
f350: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
f360: 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
f370: 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
f380: 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
f390: 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
f3a0: 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
f3b0: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
f3c0: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
f3d0: 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
f3e0: 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
f3f0: 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
f400: 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
f410: 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
f420: 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
f430: 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
f440: 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
f450: 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
f460: 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
f470: 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
f480: 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
f490: 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
f4a0: 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
f4b0: 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
f4c0: 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
f4d0: 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
f4e0: 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
f4f0: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
f500: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
f510: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
f520: 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
f530: 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
f540: 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
f550: 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
f560: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
f570: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
f580: 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
f590: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
f5a0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
f5b0: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20  gument.  ^If no 
f5c0: 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
f5d0: 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
f5e0: 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
f5f0: 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
f600: 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
f610: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
f620: 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
f630: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
f640: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
f650: 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
f660: 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
f670: 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
f680: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
f690: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
f6a0: 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
f6b0: 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
f6c0: 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
f6d0: 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
f6e0: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
f6f0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
f700: 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
f710: 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
f720: 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
f730: 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20   fired.)^.**.** 
f740: 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
f750: 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
f760: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
f770: 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
f780: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
f790: 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
f7a0: 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
f7b0: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
f7c0: 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
f7d0: 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
f7e0: 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
f7f0: 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
f800: 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
f810: 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
f820: 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
f830: 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
f840: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
f850: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
f860: 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
f870: 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
f880: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
f890: 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
f8a0: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
f8b0: 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
f8c0: 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
f8d0: 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
f8e0: 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
f8f0: 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
f900: 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
f910: 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
f920: 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
f930: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
f940: 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
f950: 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
f960: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
f970: 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
f980: 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
f990: 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
f9a0: 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
f9b0: 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
f9c0: 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
f9d0: 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
f9e0: 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
f9f0: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
fa00: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
fa10: 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
fa20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
fa30: 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
fa40: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
fa50: 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
fa60: 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
fa70: 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
fa80: 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
fa90: 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
faa0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fab0: 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
fac0: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
fad0: 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
fae0: 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
faf0: 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
fb00: 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
fb10: 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
fb20: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
fb30: 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
fb40: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
fb50: 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
fb60: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
fb70: 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
fb80: 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
fb90: 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
fba0: 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
fbb0: 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
fbc0: 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
fbd0: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
fbe0: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
fbf0: 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
fc00: 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
fc10: 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
fc20: 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
fc30: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
fc40: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
fc50: 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
fc60: 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
fc70: 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
fc80: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
fc90: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
fca0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
fcb0: 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
fcc0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
fcd0: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
fce0: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
fcf0: 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65  ** ^(Only change
fd00: 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
fd10: 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
fd20: 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
fd30: 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
fd40: 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
fd50: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
fd60: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
fd70: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
fd80: 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65  riggers or [fore
fd90: 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
fda0: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
fdb0: 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  .)^ Use the.** [
fdc0: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
fdd0: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
fde0: 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
fdf0: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
fe00: 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
fe10: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
fe20: 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
fe30: 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
fe40: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68  tions..**.** ^Ch
fe50: 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
fe60: 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74  that are simulat
fe70: 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41  ed by an [INSTEA
fe80: 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a  D OF trigger].**
fe90: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
fea0: 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62  .  Only real tab
feb0: 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  le changes are c
fec0: 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ounted..**.** ^(
fed0: 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
fee0: 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
fef0: 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
ff00: 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
ff10: 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
ff20: 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
ff30: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
ff40: 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
ff50: 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
ff60: 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
ff70: 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
ff80: 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
ff90: 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
ffa0: 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
ffb0: 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
ffc0: 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
ffd0: 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
ffe0: 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
fff0: 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e  t row changes.)^
10000 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
10010 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
10020 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
10030 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
10040 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
10050 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
10060 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
10070 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
10080 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
10090 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
100a0 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
100b0 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
100c0 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
100d0 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
100e0 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
100f0 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
10100 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
10110 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
10120 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
10130 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
10140 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
10150 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
10160 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
10170 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
10180 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
10190 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  n..**.** ^Callin
101a0 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
101b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
101c0 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
101d0 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
101e0 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
101f0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
10200 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
10210 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
10220 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
10230 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
10240 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
10250 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
10260 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
10270 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
10280 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
10290 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
102a0 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
102b0 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
102c0 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
102d0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
102e0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
102f0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
10300 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
10310 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
10320 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
10330 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
10340 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74  op level.  ^(Wit
10350 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
10360 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
10370 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
10380 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
10390 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
103a0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
103b0 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
103c0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
103d0 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
103e0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
103f0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
10400 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
10410 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
10420 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
10430 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
10440 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
10450 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
10460 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
10470 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
10480 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
10490 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a   own context.)^.
104a0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
104b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
104c0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
104d0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
104e0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
104f0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
10500 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
10510 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
10520 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
10530 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
10540 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
10550 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10560 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
10570 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
10580 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
10590 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
105a0 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
105b0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
105c0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
105d0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
105e0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
105f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
10600 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
10610 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
10620 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
10630 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
10640 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
10650 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
10660 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
10670 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
10680 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
10690 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
106a0 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
106b0 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
106c0 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
106d0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
106e0 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
106f0 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
10700 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
10710 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
10720 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
10730 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
10740 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
10750 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
10760 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
10770 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
10780 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
10790 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
107a0 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
107b0 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
107c0 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
107d0 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
107e0 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
107f0 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
10800 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
10810 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
10820 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
10830 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
10840 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
10850 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
10860 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
10870 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
10880 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
10890 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
108a0 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
108b0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
108c0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
108d0 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
108e0 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
108f0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
10900 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
10910 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
10920 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
10930 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
10940 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
10950 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
10960 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
10970 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
10980 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
10990 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
109a0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
109b0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
109c0 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
109d0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
109e0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
109f0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
10a00 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
10a10 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
10a20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10a30 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
10a40 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
10a50 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
10a60 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
10a70 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
10a80 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
10a90 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
10aa0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
10ab0 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
10ac0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
10ad0 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
10ae0 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
10af0 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
10b00 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
10b10 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
10b20 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
10b30 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
10b40 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
10b50 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
10b60 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
10b70 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
10b80 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
10b90 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
10ba0 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
10bb0 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
10bc0 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
10bd0 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
10be0 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
10bf0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
10c00 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
10c10 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
10c20 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
10c30 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
10c40 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
10c50 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
10c60 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
10c70 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
10c80 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
10c90 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
10ca0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
10cb0 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
10cc0 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
10cd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
10ce0 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
10cf0 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
10d00 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
10d10 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
10d20 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
10d30 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
10d40 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
10d50 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
10d60 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
10d70 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
10d80 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
10d90 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
10da0 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
10db0 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
10dc0 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
10dd0 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
10de0 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
10df0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
10e00 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
10e10 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
10e20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
10e30 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
10e40 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
10e50 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
10e60 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
10e70 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
10e80 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
10e90 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
10ea0 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
10eb0 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
10ec0 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
10ed0 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
10ee0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  lly..**.** ^(The
10ef0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
10f00 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
10f10 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
10f20 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
10f30 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
10f40 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
10f50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
10f60 20 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20   complete.  Any 
10f70 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
10f80 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
10f90 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
10fa0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
10fb0 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
10fc0 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
10fd0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
10fe0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
10ff0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
11000 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
11010 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
11020 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
11030 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
11040 6c 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 61 74  l.  New SQL stat
11050 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
11060 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
11070 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
11080 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
11090 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
110a0 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
110b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
110c0 65 72 72 75 70 74 28 29 2e 29 5e 0a 2a 2a 20 5e  errupt().)^.** ^
110d0 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
110e0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
110f0 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
11100 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
11110 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
11120 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
11130 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
11140 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
11150 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
11160 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
11170 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
11180 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
11190 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
111a0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
111b0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
111c0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
111d0 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
111e0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
111f0 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
11200 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
11210 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
11220 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
11230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11240 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
11250 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
11260 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
11270 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
11280 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
11290 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
112a0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
112b0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
112c0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
112d0 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
112e0 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
112f0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
11300 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
11310 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
11320 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
11330 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
11340 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
11350 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
11360 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
11370 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
11380 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
11390 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
113a0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
113b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
113c0 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
113d0 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
113e0 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
113f0 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
11400 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
11410 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
11420 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
11430 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
11440 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
11450 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
11460 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
11470 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
11480 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
11490 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
114a0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
114b0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
114c0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
114d0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
114e0 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
114f0 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
11500 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
11510 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
11520 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
11530 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
11540 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
11550 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
11560 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
11570 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
11580 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
11590 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
115a0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
115b0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
115c0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
115d0 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
115e0 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
115f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
11600 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
11610 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
11620 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
11630 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
11640 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
11650 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
11660 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
11670 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
11680 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
11690 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
116a0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
116b0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
116c0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
116d0 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
116e0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
116f0 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
11700 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
11710 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
11720 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
11730 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
11740 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
11750 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
11760 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
11770 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
11780 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
11790 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
117a0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
117b0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
117c0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
117d0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
117e0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
117f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
11800 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
11810 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
11820 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
11830 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
11840 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
11850 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
11860 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
11870 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
11880 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
11890 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
118a0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
118b0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
118c0 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
118d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
118e0 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
118f0 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
11900 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
11910 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
11920 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
11930 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
11940 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
11950 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
11960 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
11970 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
11980 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
11990 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
119a0 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
119b0 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  locked..**.** ^I
119c0 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
119d0 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
119e0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
119f0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
11a00 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
11a10 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
11a20 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
11a30 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
11a40 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
11a50 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
11a60 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
11a70 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
11a80 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
11a90 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
11aa0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
11ab0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
11ac0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
11ad0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
11ae0 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
11af0 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
11b00 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
11b10 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
11b20 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
11b30 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
11b40 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
11b50 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
11b60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
11b70 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
11b80 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
11b90 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
11ba0 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
11bb0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
11bc0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
11bd0 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
11be0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
11bf0 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
11c00 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
11c10 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
11c20 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
11c30 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
11c40 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
11c50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
11c60 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
11c70 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
11c80 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
11c90 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
11ca0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
11cb0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
11cc0 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
11cd0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
11ce0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
11cf0 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
11d00 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
11d10 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
11d20 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
11d30 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
11d40 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
11d50 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
11d60 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
11d70 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
11d80 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
11d90 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
11da0 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
11db0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
11dc0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
11dd0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
11de0 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
11df0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
11e00 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
11e10 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
11e20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
11e30 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
11e40 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
11e50 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
11e60 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
11e70 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
11e80 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
11e90 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
11ea0 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
11eb0 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
11ec0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
11ed0 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
11ee0 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
11ef0 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
11f00 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
11f10 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
11f20 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
11f30 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
11f40 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
11f50 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
11f60 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
11f70 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
11f80 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
11f90 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
11fa0 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
11fb0 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
11fc0 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
11fd0 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
11fe0 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
11ff0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
12000 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
12010 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
12020 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
12030 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
12040 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
12050 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
12060 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
12070 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
12080 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
12090 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
120a0 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
120b0 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
120c0 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
120d0 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
120e0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
120f0 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
12100 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
12110 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
12120 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
12130 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
12140 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
12150 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
12160 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
12170 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
12180 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
12190 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
121a0 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
121b0 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
121c0 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
121d0 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
121e0 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
121f0 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
12200 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
12210 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
12220 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
12230 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49  .** readers.  ^I
12240 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
12250 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
12260 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
12270 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
12280 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
12290 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
122a0 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
122b0 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
122c0 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
122d0 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
122e0 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
122f0 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
12300 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
12310 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
12320 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63  .  ^This error c
12330 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
12340 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
12350 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
12360 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
12370 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
12380 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
12390 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
123a0 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
123b0 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
123c0 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
123d0 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
123e0 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
123f0 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
12400 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
12410 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
12420 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
12430 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
12440 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
12450 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
12460 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
12470 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
12480 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
12490 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
124a0 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
124b0 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
124c0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
124d0 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c  imeout()].** wil
124e0 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
124f0 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e  ear the busy han
12500 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
12510 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
12520 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
12530 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
12540 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
12550 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12560 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
12570 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
12580 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
12590 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
125a0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
125b0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
125c0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
125d0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
125e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
125f0 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
12600 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
12610 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
12620 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
12630 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
12640 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
12650 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
12660 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
12670 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
12680 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
12690 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
126a0 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
126b0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
126c0 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
126d0 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
126e0 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
126f0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
12700 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
12710 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
12720 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
12730 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
12740 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
12750 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
12760 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
12770 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
12780 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
12790 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
127a0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
127b0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
127c0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
127d0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
127e0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
127f0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
12800 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
12810 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
12820 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
12830 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
12840 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
12850 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
12860 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
12870 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
12880 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
12890 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
128a0 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
128b0 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
128c0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
128d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
128e0 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
128f0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
12900 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
12910 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
12920 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
12930 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
12940 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
12950 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
12960 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
12970 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
12980 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e  cleared.)^.*/.in
12990 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
129a0 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
129b0 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
129c0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
129d0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
129e0 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
129f0 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ies.**.** Defini
12a00 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
12a10 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
12a20 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
12a30 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
12a40 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
12a50 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
12a60 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
12a70 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
12a80 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
12a90 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
12aa0 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
12ab0 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
12ac0 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
12ad0 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
12ae0 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
12af0 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
12b00 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
12b10 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
12b20 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
12b30 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
12b40 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
12b50 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
12b60 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
12b70 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
12b80 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
12b90 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
12ba0 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
12bb0 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
12bc0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
12bd0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
12be0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
12bf0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
12c00 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
12c10 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
12c20 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
12c30 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
12c40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
12c50 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
12c60 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
12c70 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
12c80 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
12c90 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
12ca0 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
12cb0 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
12cc0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
12cd0 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
12ce0 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
12cf0 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
12d00 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
12d10 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
12d20 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
12d30 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
12d40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
12d50 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
12d60 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
12d70 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
12d80 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
12d90 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
12da0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
12db0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
12dc0 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
12dd0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
12de0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
12df0 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
12e00 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
12e10 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
12e20 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e  ()]..**.** As an
12e30 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
12e40 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
12e50 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
12e60 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
12e70 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
12e80 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
12e90 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
12ea0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
12eb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
12ec0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
12ed0 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
12ee0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
12ef0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
12f00 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
12f10 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
12f20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
12f30 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
12f40 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
12f50 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
12f60 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
12f70 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
12f80 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
12f90 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
12fa0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
12fb0 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
12fc0 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
12fd0 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
12fe0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
12ff0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
13000 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
13010 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
13020 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
13030 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
13040 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
13050 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
13060 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
13070 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
13080 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
13090 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
130a0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
130b0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
130c0 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
130d0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
130e0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
130f0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
13100 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
13110 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
13120 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
13130 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
13140 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
13150 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
13160 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
13170 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
13180 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
13190 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
131a0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
131b0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
131c0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
131d0 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
131e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
131f0 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
13200 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
13210 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
13220 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
13230 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
13240 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
13250 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
13260 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
13270 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
13280 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 73  table(),.** it s
13290 68 6f 75 6c 64 20 70 61 73 73 20 74 68 65 20 72  hould pass the r
132a0 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
132b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
132c0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
132d0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
132e0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
132f0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
13300 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
13310 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
13320 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
13330 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
13340 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
13350 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
13360 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
13370 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
13380 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
13390 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
133a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
133b0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
133c0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
133d0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
133e0 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
133f0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
13400 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
13410 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
13420 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
13430 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
13440 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
13450 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
13460 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
13470 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
13480 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
13490 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
134a0 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
134b0 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
134c0 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
134d0 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
134e0 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
134f0 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
13500 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
13510 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
13520 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
13530 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
13540 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
13550 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
13560 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
13570 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
13580 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
13590 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
135a0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a  3_errmsg()].)^.*
135b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
135c0 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
135d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
135e0 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
135f0 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
13600 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
13610 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
13620 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
13630 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
13640 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
13650 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
13660 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
13670 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
13680 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
13690 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
136a0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
136b0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
136c0 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
136d0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
136e0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
136f0 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
13700 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
13710 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
13720 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
13730 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
13740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13750 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
13760 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
13770 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
13780 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
13790 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
137a0 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
137b0 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
137c0 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
137d0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
137e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
137f0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
13800 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
13810 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
13820 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
13830 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
13840 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
13850 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13860 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
13870 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
13880 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
13890 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
138a0 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
138b0 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
138c0 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
138d0 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
138e0 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
138f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
13900 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
13910 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
13920 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
13930 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
13940 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c 69  .**.** ^(In sqli
13950 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
13960 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
13970 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
13980 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
13990 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
139a0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
139b0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
139c0 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
139d0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
139e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
139f0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
13a00 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
13a10 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
13a20 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
13a30 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
13a40 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
13a50 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
13a60 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
13a70 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
13a80 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
13a90 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
13aa0 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
13ab0 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
13ac0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
13ad0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
13ae0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
13af0 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
13b00 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
13b10 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
13b20 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
13b30 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
13b40 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
13b50 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
13b60 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
13b70 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
13b80 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
13b90 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
13ba0 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
13bb0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
13bc0 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
13bd0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
13be0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
13bf0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
13c00 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
13c10 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
13c20 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
13c30 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
13c40 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
13c50 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
13c60 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
13c70 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
13c80 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
13c90 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
13ca0 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
13cb0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
13cc0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
13cd0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
13ce0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
13cf0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
13d00 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
13d10 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
13d20 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
13d30 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
13d40 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
13d50 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
13d60 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
13d70 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
13d80 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
13d90 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
13da0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
13db0 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
13dc0 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
13dd0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
13de0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
13df0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
13e00 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
13e10 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
13e20 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
13e30 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
13e40 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
13e50 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
13e60 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
13e70 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
13e80 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
13e90 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
13ea0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
13eb0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
13ec0 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
13ed0 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
13ee0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
13ef0 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
13f00 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
13f10 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
13f20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
13f30 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
13f40 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
13f50 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
13f60 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
13f70 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
13f80 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
13f90 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
13fa0 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
13fb0 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
13fc0 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
13fd0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
13fe0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
13ff0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
14000 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
14010 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
14020 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14030 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
14040 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
14050 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
14060 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
14070 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
14080 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
14090 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
140a0 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
140b0 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
140c0 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
140d0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
140e0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
140f0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
14100 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
14110 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
14120 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
14130 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
14140 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
14150 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
14160 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
14170 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
14180 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
14190 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
141a0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
141b0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
141c0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
141d0 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
141e0 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
141f0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14200 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
14210 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
14220 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
14230 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
14240 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
14250 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
14260 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
14270 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
14280 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
14290 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
142a0 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
142b0 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
142c0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
142d0 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
142e0 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
142f0 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
14300 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
14310 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
14320 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
14330 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
14340 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
14350 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
14360 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
14370 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
14380 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
14390 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
143a0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
143b0 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
143c0 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
143d0 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
143e0 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
143f0 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
14400 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
14410 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
14420 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
14430 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
14440 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
14450 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
14460 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
14470 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
14480 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
14490 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
144a0 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
144b0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
144c0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
144d0 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
144e0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
144f0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
14500 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
14510 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
14520 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
14530 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
14540 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
14550 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
14560 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
14570 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
14580 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
14590 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
145a0 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
145b0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
145c0 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
145d0 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
145e0 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
145f0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
14600 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
14610 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
14620 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
14630 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
14640 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
14650 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
14660 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
14670 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
14680 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
14690 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
146a0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
146b0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
146c0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
146d0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
146e0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
146f0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
14700 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
14710 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
14720 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
14730 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
14740 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
14750 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
14760 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
14770 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
14780 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14790 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
147a0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
147b0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
147c0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
147d0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
147e0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
147f0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
14800 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
14810 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
14820 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
14830 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
14840 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
14850 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14860 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
14870 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
14880 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
14890 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
148a0 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
148b0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
148c0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
148d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
148e0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
148f0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
14900 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
14910 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
14920 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
14930 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
14940 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
14950 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
14960 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
14970 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14980 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
14990 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
149a0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
149b0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
149c0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
149d0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
149e0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
149f0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
14a00 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
14a10 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
14a20 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
14a30 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
14a40 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
14a50 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
14a60 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
14a70 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
14a80 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
14a90 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
14aa0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
14ab0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
14ac0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
14ad0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
14ae0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
14af0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
14b00 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
14b10 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
14b20 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
14b30 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
14b40 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
14b50 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
14b60 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
14b70 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
14b80 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
14b90 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
14ba0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
14bb0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
14bc0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
14bd0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
14be0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
14bf0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
14c00 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
14c10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
14c20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
14c30 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
14c40 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
14c50 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
14c60 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
14c70 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
14c80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
14c90 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
14ca0 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
14cb0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
14cc0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
14cd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14ce0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
14cf0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
14d00 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
14d10 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14d20 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
14d30 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
14d40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
14d50 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
14d60 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
14d70 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
14d80 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
14d90 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
14da0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
14db0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14dc0 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
14dd0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14de0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
14df0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
14e00 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
14e10 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
14e20 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
14e30 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
14e40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
14e50 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
14e60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
14e70 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
14e80 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
14e90 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
14ea0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
14eb0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
14ec0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
14ed0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
14ee0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
14ef0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
14f00 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
14f10 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
14f20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
14f30 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
14f40 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
14f50 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
14f60 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
14f70 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
14f80 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
14f90 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
14fa0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
14fb0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
14fc0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
14fd0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
14fe0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
14ff0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
15000 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
15010 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
15020 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
15030 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
15040 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
15050 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
15060 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
15070 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
15080 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
15090 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
150a0 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ary..**.** In SQ
150b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
150c0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
150d0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
150e0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
150f0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
15100 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
15110 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
15120 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
15130 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
15140 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
15150 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
15160 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
15170 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
15180 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
15190 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
151a0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
151b0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
151c0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
151d0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
151e0 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ls.** the system
151f0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
15200 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
15210 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
15220 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
15230 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
15240 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
15250 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
15260 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
15270 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
15280 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
15290 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
152a0 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
152b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
152c0 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ors are detected
152d0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72  , but.** they ar
152e0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
152f0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
15300 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
15310 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
15320 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
15330 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
15340 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
15350 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
15360 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
15370 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
15380 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
15390 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
153a0 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
153b0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
153c0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
153d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
153e0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
153f0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
15400 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
15410 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
15420 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
15430 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
15440 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
15450 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
15460 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
15470 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
15480 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
15490 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
154a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
154b0 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
154c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
154d0 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
154e0 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
154f0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
15500 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
15510 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15520 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
15530 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
15540 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
15550 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
15560 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
15570 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
15580 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
15590 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
155a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
155b0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
155c0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
155d0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
155e0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
155f0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
15600 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
15610 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
15620 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
15630 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
15640 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
15650 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
15660 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
15670 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
15680 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
15690 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
156a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
156b0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
156c0 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
156d0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
156e0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
156f0 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
15700 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
15710 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
15720 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
15730 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
15740 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
15750 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
15760 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
15770 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
15780 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
15790 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
157a0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
157b0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
157c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
157d0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
157e0 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
157f0 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
15800 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
15810 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
15820 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15830 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
15840 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
15850 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
15860 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
15870 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
15880 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
15890 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
158a0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
158b0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
158c0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
158d0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
158e0 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
158f0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
15900 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
15910 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
15920 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
15930 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
15940 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
15950 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
15960 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
15970 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
15980 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
15990 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
159a0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
159b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
159c0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
159d0 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
159e0 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
159f0 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
15a00 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
15a10 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
15a20 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
15a30 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
15a40 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
15a50 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
15a60 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
15a70 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
15a80 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
15a90 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
15aa0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
15ab0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
15ac0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
15ad0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
15ae0 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
15af0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
15b00 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
15b10 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
15b20 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
15b30 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
15b40 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
15b50 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
15b60 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
15b70 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
15b80 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
15b90 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
15ba0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
15bb0 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
15bc0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74   is invoked (eit
15bd0 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f  her internally o
15be0 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c  r by.** the appl
15bf0 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e  ication) the PRN
15c00 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
15c10 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
15c20 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68  ained.** from th
15c30 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
15c40 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
15c50 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
15c60 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e  ] object..** ^On
15c70 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
15c80 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
15c90 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
15ca0 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
15cb0 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
15cc0 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
15cd0 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
15ce0 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
15cf0 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
15d00 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
15d10 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
15d20 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
15d30 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
15d40 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
15d50 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
15d60 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
15d70 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
15d80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15d90 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
15da0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
15db0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
15dc0 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
15dd0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
15de0 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
15df0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
15e00 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
15e10 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
15e20 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
15e30 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
15e40 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
15e50 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
15e60 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
15e70 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
15e80 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
15e90 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
15ea0 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
15eb0 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
15ec0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
15ed0 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
15ee0 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
15ef0 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
15f00 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
15f10 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
15f20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
15f30 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
15f40 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
15f50 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
15f60 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
15f70 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
15f80 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
15f90 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
15fa0 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
15fb0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
15fc0 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
15fd0 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
15fe0 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
15ff0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
16000 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
16010 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
16020 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
16030 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
16040 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
16050 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
16060 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
16070 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
16080 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
16090 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
160a0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
160b0 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
160c0 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
160d0 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
160e0 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
160f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
16100 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
16110 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
16120 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
16130 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
16140 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
16150 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
16160 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
16170 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
16180 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
16190 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
161a0 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
161b0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
161c0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
161d0 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
161e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
161f0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
16200 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
16210 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
16220 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
16230 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
16240 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
16250 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
16260 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
16270 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
16280 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
16290 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
162a0 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
162b0 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
162c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
162d0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
162e0 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
162f0 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
16300 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
16310 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
16320 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
16330 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
16340 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
16350 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
16360 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
16370 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
16380 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
16390 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
163a0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
163b0 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
163c0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
163d0 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
163e0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
163f0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
16400 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
16410 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
16420 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
16430 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
16440 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
16450 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
16460 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
16470 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
16480 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
16490 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
164a0 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
164b0 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
164c0 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
164d0 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
164e0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
164f0 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
16500 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
16510 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
16520 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
16530 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
16540 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
16550 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
16560 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
16570 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
16580 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
16590 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
165a0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
165b0 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
165c0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
165d0 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
165e0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
165f0 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
16600 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
16610 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
16620 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
16630 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
16640 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
16650 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
16660 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
16670 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
16680 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
16690 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
166a0 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
166b0 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
166c0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
166d0 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
166e0 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
166f0 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
16700 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
16710 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
16720 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
16730 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
16740 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
16750 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
16760 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
16770 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
16780 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
16790 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
167a0 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
167b0 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
167c0 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
167d0 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
167e0 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
167f0 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
16800 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
16810 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
16820 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
16830 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
16840 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
16850 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
16860 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
16870 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
16880 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
16890 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
168a0 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
168b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
168c0 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
168d0 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
168e0 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
168f0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
16900 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
16910 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
16920 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
16930 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
16940 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
16950 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
16960 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
16970 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
16980 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
16990 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
169a0 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
169b0 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
169c0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
169d0 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
169e0 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
169f0 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
16a00 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
16a10 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
16a20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
16a30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16a40 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
16a50 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
16a60 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16a70 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
16a80 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
16a90 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
16aa0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
16ab0 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
16ac0 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
16ad0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
16ae0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
16af0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
16b00 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16b10 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
16b20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
16b30 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
16b40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
16b50 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
16b60 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
16b70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
16b80 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
16b90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
16ba0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
16bb0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
16bc0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
16bd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
16be0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
16bf0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
16c00 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
16c10 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
16c20 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
16c30 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
16c40 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
16c50 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
16c60 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
16c70 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
16c80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
16c90 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
16ca0 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
16cb0 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
16cc0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
16cd0 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
16ce0 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
16cf0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
16d00 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
16d10 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
16d20 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
16d30 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
16d40 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16d50 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
16d60 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
16d70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
16d80 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
16d90 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
16da0 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
16db0 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
16dc0 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
16dd0 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
16de0 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
16df0 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
16e00 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
16e10 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
16e20 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
16e30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16e40 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
16e50 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
16e60 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
16e70 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
16e80 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16e90 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
16ea0 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
16eb0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
16ec0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
16ed0 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
16ee0 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
16ef0 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
16f00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
16f10 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
16f20 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
16f30 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
16f40 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
16f50 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
16f60 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
16f70 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
16f80 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
16f90 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
16fa0 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
16fb0 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
16fc0 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
16fd0 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
16fe0 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
16ff0 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
17000 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
17010 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
17020 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
17030 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
17040 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
17050 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17060 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
17070 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
17080 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
17090 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
170a0 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
170b0 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
170c0 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
170d0 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
170e0 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
170f0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
17100 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
17110 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
17120 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
17130 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
17140 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
17150 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
17160 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
17170 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
17180 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
17190 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
171a0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
171b0 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
171c0 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
171d0 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
171e0 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
171f0 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
17200 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
17210 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
17220 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
17230 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
17240 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
17250 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
17260 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
17270 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
17280 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
17290 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
172a0 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
172b0 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
172c0 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
172d0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
172e0 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
172f0 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
17300 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
17310 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
17320 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
17330 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
17340 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
17350 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20  arameter.  ^The 
17360 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
17370 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
17380 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
17390 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
173a0 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
173b0 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
173c0 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
173d0 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
173e0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
173f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
17400 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
17410 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
17420 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
17430 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
17440 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
17450 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
17460 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
17470 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
17480 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
17490 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
174a0 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
174b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
174c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
174d0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
174e0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
174f0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
17500 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
17510 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
17520 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
17530 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
17540 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17550 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
17560 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
17570 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
17580 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17590 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
175a0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
175b0 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
175c0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
175d0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
175e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
175f0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
17600 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
17610 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17620 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
17630 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17640 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
17650 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
17660 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
17670 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17680 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17690 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
176a0 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
176b0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
176c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
176d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
176e0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
176f0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
17700 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
17710 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
17720 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17730 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
17740 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
17750 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
17760 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17770 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17780 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
17790 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
177a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
177b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
177c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
177d0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
177e0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
177f0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
17800 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
17810 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
17820 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
17830 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
17840 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
17850 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
17860 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
17870 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
17880 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
17890 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
178a0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
178b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
178c0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
178d0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
178e0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
178f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
17900 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
17910 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
17920 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
17930 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
17940 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
17950 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
17960 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
17970 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
17980 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17990 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
179a0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
179b0 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
179c0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
179d0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
179e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
179f0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
17a00 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
17a10 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
17a20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
17a30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17a40 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
17a50 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
17a60 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
17a70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17a80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17a90 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
17aa0 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
17ab0 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
17ac0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
17ad0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
17ae0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
17af0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
17b00 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17b10 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
17b20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17b30 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
17b40 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
17b50 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17b60 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17b70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17b80 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
17b90 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
17ba0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
17bb0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17bc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17bd0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
17be0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
17bf0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
17c00 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
17c10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17c20 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
17c30 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
17c40 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
17c50 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17c60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17c70 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
17c80 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
17c90 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
17ca0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17cb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
17cc0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
17cd0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
17ce0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
17cf0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
17d00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
17d10 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
17d20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
17d30 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
17d40 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
17d50 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
17d60 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
17d70 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
17d80 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
17d90 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17da0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
17db0 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
17dc0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
17dd0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
17de0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
17df0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
17e00 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
17e10 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
17e20 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
17e30 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
17e40 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
17e50 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
17e60 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
17e70 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
17e80 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
17e90 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
17ea0 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
17eb0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
17ec0 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
17ed0 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
17ee0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
17ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
17f00 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
17f10 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
17f20 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
17f30 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
17f40 63 74 69 6f 6e 73 0a 2a 2a 20 45 58 50 45 52 49  ctions.** EXPERI
17f50 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
17f60 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
17f70 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
17f80 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
17f90 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
17fa0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
17fb0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
17fc0 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
17fd0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
17fe0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
17ff0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
18000 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
18010 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
18020 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
18030 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
18040 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
18050 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
18060 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
18070 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
18080 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18090 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
180a0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
180b0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
180c0 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
180d0 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
180e0 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
180f0 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
18100 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
18110 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
18120 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
18130 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
18140 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
18150 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
18160 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
18170 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
18180 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
18190 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
181a0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
181b0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
181c0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
181d0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
181e0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
181f0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
18200 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
18210 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
18220 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
18230 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
18240 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
18250 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
18260 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
18270 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
18280 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
18290 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
182a0 20 72 75 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   run..*/.SQLITE_
182b0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
182c0 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
182d0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
182e0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
182f0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
18300 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
18310 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
18320 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
18330 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
18340 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
18350 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
18360 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
18370 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
18380 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
18390 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
183a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
183b0 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20  tine configures 
183c0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
183d0 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f  ion - the.** pro
183e0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d  gress callback -
183f0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
18400 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
18410 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e  ring long.** run
18420 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ning calls to [s
18430 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
18440 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
18450 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
18460 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20  _get_table()].  
18470 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
18480 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
18490 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
184a0 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
184b0 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
184c0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ry..**.** ^If th
184d0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
184e0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
184f0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
18500 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
18510 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
18520 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
18530 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
18540 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
18550 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
18560 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
18570 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
18580 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  ess handler must
18590 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
185a0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
185b0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
185c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
185d0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
185e0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
185f0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
18600 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
18610 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
18620 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
18630 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
18640 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18650 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
18660 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
18670 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
18680 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
18690 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
186a0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
186b0 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
186c0 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
186d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
186e0 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
186f0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
18700 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
18710 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
18720 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
18730 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20  e whose name is 
18740 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20  given by the.** 
18750 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
18760 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
18770 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
18780 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
18790 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
187a0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
187b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
187c0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
187d0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
187e0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
187f0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
18800 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
18810 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
18820 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
18830 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
18840 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
18850 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
18860 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
18870 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
18880 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
18890 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
188a0 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
188b0 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
188c0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
188d0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
188e0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
188f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
18900 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
18910 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
18920 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
18930 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
18940 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
18950 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
18960 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
18970 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
18980 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
18990 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
189a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
189b0 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
189c0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
189d0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
189e0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
189f0 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
18a00 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
18a10 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
18a20 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
18a30 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
18a40 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
18a50 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
18a60 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
18a70 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
18a80 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
18a90 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
18aa0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
18ab0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
18ac0 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
18ad0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
18ae0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
18af0 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
18b00 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
18b10 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
18b20 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
18b30 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
18b40 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
18b50 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
18b60 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
18b70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
18b80 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
18b90 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
18ba0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
18bb0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
18bc0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
18bd0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
18be0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
18bf0 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
18c00 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
18c10 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
18c20 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
18c30 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
18c40 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
18c50 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
18c60 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
18c70 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
18c80 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
18c90 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
18ca0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
18cb0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
18cc0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
18cd0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
18ce0 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
18cf0 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
18d00 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
18d10 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
18d20 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
18d30 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
18d40 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
18d50 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  CHE],.** and/or 
18d60 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
18d70 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73  VATECACHE] flags
18d80 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
18d90 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
18da0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
18db0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
18dc0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
18dd0 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
18de0 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
18df0 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
18e00 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
18e10 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
18e20 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
18e30 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
18e40 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
18e50 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
18e60 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
18e70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
18e80 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
18e90 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
18ea0 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
18eb0 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
18ec0 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
18ed0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
18ee0 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
18ef0 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
18f00 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
18f10 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
18f20 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
18f30 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
18f40 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
18f50 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
18f60 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
18f70 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
18f80 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
18f90 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
18fa0 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
18fb0 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
18fc0 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69  eates it if.** i
18fd0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
18fe0 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
18ff0 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
19000 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
19010 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
19020 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
19030 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
19040 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
19050 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
19060 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
19070 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
19080 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
19090 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
190a0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20   shown above or 
190b0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69  one of the combi
190c0 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
190d0 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20  ove combined.** 
190e0 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
190f0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
19100 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
19110 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c  LMUTEX],.** [SQL
19120 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
19130 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51  ACHE] and/or [SQ
19140 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
19150 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a  CACHE] flags,.**
19160 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
19170 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
19180 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
19190 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
191a0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
191b0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
191c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
191d0 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
191e0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
191f0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
19200 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
19210 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
19220 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
19230 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
19240 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
19250 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
19260 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
19270 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
19280 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
19290 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
192a0 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
192b0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
192c0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
192d0 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
192e0 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
192f0 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
19300 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
19310 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
19320 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
19330 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
19340 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
19350 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19360 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
19370 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
19380 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
19390 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
193a0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
193b0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
193c0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
193d0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
193e0 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
193f0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
19400 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
19410 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
19420 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
19430 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
19440 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
19450 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
19460 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
19470 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
19480 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
19490 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
194a0 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
194b0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
194c0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
194d0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
194e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
194f0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
19500 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
19510 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
19520 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19530 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
19540 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
19550 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
19560 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
19570 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
19580 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
19590 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
195a0 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
195b0 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
195c0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
195d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
195e0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
195f0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
19600 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
19610 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
19620 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
19630 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
19640 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
19650 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
19660 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
19670 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
19680 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
19690 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
196a0 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
196b0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
196c0 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
196d0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
196e0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
196f0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
19700 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
19710 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
19720 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
19730 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
19740 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
19750 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
19760 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
19770 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
19780 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
19790 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
197a0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
197b0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
197c0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
197d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
197e0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
197f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
19800 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
19810 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
19820 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
19830 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
19840 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
19850 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
19860 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
19870 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
19880 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
19890 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
198a0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
198b0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
198c0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
198d0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
198e0 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
198f0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
19900 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
19910 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
19920 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
19930 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
19940 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
19950 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
19960 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
19970 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
19980 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19990 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
199a0 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
199b0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
199c0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
199d0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
199e0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
199f0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
19a00 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
19a10 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
19a20 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
19a30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
19a40 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
19a50 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
19a60 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
19a70 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
19a80 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
19a90 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
19aa0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
19ab0 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
19ac0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
19ad0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
19ae0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
19af0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
19b00 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
19b10 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
19b20 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
19b30 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
19b40 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
19b50 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
19b60 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
19b70 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
19b80 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
19b90 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
19ba0 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
19bb0 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
19bc0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
19bd0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
19be0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
19bf0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
19c00 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
19c10 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
19c20 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
19c30 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
19c40 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
19c50 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
19c60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19c70 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
19c80 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
19c90 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
19ca0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
19cb0 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
19cc0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
19cd0 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
19ce0 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
19cf0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
19d00 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
19d10 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
19d20 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
19d30 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
19d40 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
19d50 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
19d60 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
19d70 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
19d80 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
19d90 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
19da0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
19db0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
19dc0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
19dd0 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
19de0 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
19df0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
19e00 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
19e10 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
19e20 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
19e30 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
19e40 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
19e50 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
19e60 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
19e70 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
19e80 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
19e90 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
19ea0 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
19eb0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
19ec0 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
19ed0 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
19ee0 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
19ef0 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
19f00 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
19f10 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
19f20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
19f30 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65  ons.)^.**.** Whe
19f40 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
19f50 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
19f60 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
19f70 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
19f80 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
19f90 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
19fa0 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
19fb0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
19fc0 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
19fd0 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
19fe0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
19ff0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
1a000 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
1a010 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
1a020 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
1a030 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
1a040 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
1a050 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
1a060 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1a070 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
1a080 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
1a090 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
1a0a0 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
1a0b0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
1a0c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
1a0d0 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
1a0e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
1a0f0 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
1a100 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
1a110 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
1a120 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
1a130 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
1a140 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
1a150 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
1a160 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
1a170 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
1a180 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
1a190 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
1a1a0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
1a1b0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
1a1c0 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
1a1d0 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
1a1e0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
1a1f0 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
1a200 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
1a210 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
1a220 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
1a230 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
1a240 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
1a250 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
1a260 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
1a270 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1a280 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
1a290 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1a2a0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
1a2b0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1a2c0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
1a2d0 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
1a2e0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
1a2f0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  6(sqlite3*);../*
1a300 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1a310 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
1a320 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
1a330 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1a340 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
1a350 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
1a360 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
1a370 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
1a380 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
1a390 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1a3a0 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
1a3b0 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
1a3c0 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
1a3d0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
1a3e0 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
1a3f0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
1a400 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
1a410 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
1a420 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
1a430 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
1a440 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
1a450 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
1a460 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
1a470 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1a480 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1a490 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
1a4a0 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
1a4b0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
1a4c0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
1a4d0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
1a4e0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1a4f0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
1a500 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
1a510 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
1a520 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
1a530 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a540 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
1a550 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
1a560 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
1a570 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
1a580 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
1a590 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
1a5a0 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
1a5b0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
1a5c0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
1a5d0 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
1a5e0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1a5f0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
1a600 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
1a610 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
1a620 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
1a630 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
1a640 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1a650 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
1a660 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1a670 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
1a680 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
1a690 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
1a6a0 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
1a6b0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
1a6c0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
1a6d0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
1a6e0 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
1a6f0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
1a700 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
1a710 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
1a720 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1a730 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
1a740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a750 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
1a760 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
1a770 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
1a780 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a790 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
1a7a0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
1a7b0 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
1a7c0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
1a7d0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
1a7e0 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
1a7f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
1a800 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
1a810 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
1a820 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63  truct.  The func
1a830 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1a840 20 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a   old limit.)^.**
1a850 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
1a860 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
1a870 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
1a880 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
1a890 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68 65  ed..** ^(For the
1a8a0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
1a8b0 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  of SQLITE_LIMIT_
1a8c0 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a  XYZ there is a .
1a8d0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
1a8e0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
1a8f0 2a 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69  * set by a compi
1a900 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f  le-time C prepro
1a910 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d  cessor macro nam
1a920 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  ed .** [limits |
1a930 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d   SQLITE_MAX_XYZ]
1a940 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
1a950 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
1a960 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
1a970 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
1a980 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
1a990 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
1a9a0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
1a9b0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
1a9c0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
1a9d0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
1a9e0 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52  r limit..**.** R
1a9f0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
1aa00 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
1aa10 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
1aa20 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
1aa30 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
1aa40 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
1aa50 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
1aa60 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
1aa70 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
1aa80 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
1aa90 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
1aaa0 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
1aab0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
1aac0 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
1aad0 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
1aae0 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
1aaf0 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
1ab00 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
1ab10 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
1ab20 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
1ab30 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
1ab40 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
1ab50 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
1ab60 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
1ab70 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
1ab80 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
1ab90 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
1aba0 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
1abb0 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
1abc0 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
1abd0 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
1abe0 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
1abf0 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
1ac00 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
1ac10 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
1ac20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
1ac30 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
1ac40 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
1ac50 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1ac60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
1ac70 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
1ac80 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
1ac90 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
1aca0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
1acb0 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
1acc0 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
1acd0 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
1ace0 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
1acf0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1ad00 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
1ad10 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
1ad20 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
1ad30 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
1ad40 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
1ad50 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
1ad60 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
1ad70 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
1ad80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1ad90 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
1ada0 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
1adb0 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
1adc0 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
1add0 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
1ade0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
1adf0 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
1ae00 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
1ae10 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
1ae20 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
1ae30 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
1ae40 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
1ae50 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
1ae60 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
1ae70 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
1ae80 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
1ae90 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
1aea0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
1aeb0 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
1aec0 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
1aed0 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
1aee0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1aef0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1af00 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1af10 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
1af20 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
1af30 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
1af40 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  row.<dd>)^.**.**
1af50 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1af60 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
1af70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1af80 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1af90 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1afa0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
1afb0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1afc0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
1afd0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1afe0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1aff0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
1b000 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
1b010 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
1b020 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
1b030 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
1b040 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1b050 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
1b060 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
1b070 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
1b080 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
1b090 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1b0a0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1b0b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1b0c0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1b0d0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
1b0e0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
1b0f0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
1b100 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1b110 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1b120 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
1b130 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1b140 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
1b150 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
1b160 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1b170 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1b180 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1b190 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
1b1a0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1b1b0 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
1b1c0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
1b1d0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
1b1e0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
1b1f0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
1b200 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
1b210 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1b220 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1b230 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
1b240 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1b250 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
1b260 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
1b270 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1b280 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
1b290 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
1b2a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1b2b0 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
1b2c0 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
1b2d0 61 62 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a  abases].</dd>.**
1b2e0 0a 2a 2a 20 5e 3c 64 74 3e 53 51 4c 49 54 45 5f  .** ^<dt>SQLITE_
1b2f0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1b300 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
1b310 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1b320 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
1b330 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
1b340 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
1b350 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
1b360 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
1b370 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1b380 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1b390 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
1b3a0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1b3b0 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c  umber of variabl
1b3c0 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  es in an SQL sta
1b3d0 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a  tement that can.
1b3e0 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64  ** be bound.</dd
1b3f0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1b400 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
1b410 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
1b420 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1b430 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
1b440 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
1b450 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
1b460 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
1b470 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1b480 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1b490 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
1b4a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1b4b0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1b4c0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
1b4d0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1b4e0 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
1b4f0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
1b500 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
1b510 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
1b520 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
1b530 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1b540 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
1b550 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
1b560 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1b570 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
1b580 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
1b590 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1b5a0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
1b5b0 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
1b5c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1b5d0 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
1b5e0 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
1b5f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1b600 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1b610 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
1b620 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1b630 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1b640 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
1b650 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b660 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
1b670 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
1b680 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
1b690 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
1b6a0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
1b6b0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1b6c0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
1b6d0 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
1b6e0 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
1b6f0 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
1b700 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
1b710 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
1b720 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
1b730 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
1b740 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
1b750 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
1b760 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
1b770 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b780 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1b790 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
1b7a0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1b7b0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1b7c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1b7d0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1b7e0 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
1b7f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b800 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
1b810 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
1b820 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
1b830 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
1b840 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
1b850 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
1b860 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
1b870 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
1b880 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
1b890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1b8a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1b8b0 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
1b8c0 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
1b8d0 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
1b8e0 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
1b8f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1b900 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
1b910 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
1b920 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
1b930 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
1b940 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
1b950 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
1b960 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
1b970 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
1b980 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
1b990 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
1b9a0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1b9b0 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
1b9c0 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
1b9d0 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
1b9e0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
1b9f0 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
1ba00 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
1ba10 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
1ba20 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
1ba30 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
1ba40 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
1ba50 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
1ba60 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
1ba70 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
1ba80 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
1ba90 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
1baa0 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
1bab0 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
1bac0 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
1bad0 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
1bae0 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
1baf0 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
1bb00 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
1bb10 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
1bb20 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
1bb30 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1bb40 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
1bb50 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
1bb60 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a  rminator bytes..
1bb70 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
1bb80 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
1bb90 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
1bba0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
1bbb0 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
1bbc0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
1bbd0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
1bbe0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
1bbf0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
1bc00 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
1bc10 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
1bc20 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
1bc30 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
1bc40 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
1bc50 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
1bc60 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
1bc70 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
1bc80 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
1bc90 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
1bca0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1bcb0 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
1bcc0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1bcd0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
1bce0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
1bcf0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
1bd00 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
1bd10 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
1bd20 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
1bd30 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
1bd40 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
1bd50 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
1bd60 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
1bd70 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
1bd80 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
1bd90 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
1bda0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
1bdb0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
1bdc0 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
1bdd0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1bde0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1bdf0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
1be00 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
1be10 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
1be20 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
1be30 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
1be40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1be50 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
1be60 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
1be70 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
1be80 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1be90 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1bea0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1beb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1bec0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1bed0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
1bee0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
1bef0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
1bf00 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
1bf10 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
1bf20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
1bf30 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
1bf40 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1bf50 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
1bf60 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
1bf70 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
1bf80 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
1bf90 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
1bfa0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
1bfb0 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
1bfc0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
1bfd0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
1bfe0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
1bff0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
1c000 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
1c010 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
1c020 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
1c030 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
1c040 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
1c050 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
1c060 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
1c070 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1c080 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
1c090 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
1c0a0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
1c0b0 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
1c0c0 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
1c0d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1c0e0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
1c0f0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
1c100 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
1c110 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
1c120 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 5e 49  un it again.  ^I
1c130 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
1c140 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61   changed in.** a
1c150 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
1c160 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
1c170 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
1c180 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c190 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
1c1a0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
1c1b0 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
1c1c0 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
1c1d0 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
1c1e0 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
1c1f0 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
1c200 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
1c210 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1c220 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
1c230 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
1c240 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
1c250 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
1c260 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
1c270 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
1c280 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
1c290 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
1c2a0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
1c2b0 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c  MA] return..** <
1c2c0 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1c2d0 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
1c2e0 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
1c2f0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1c300 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
1c310 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
1c320 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
1c330 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
1c340 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
1c350 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
1c360 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
1c370 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
1c380 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
1c390 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
1c3a0 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
1c3b0 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c  .** and you woul
1c3c0 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
1c3d0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
1c3e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1c3f0 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  ] in order.** to
1c400 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
1c410 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
1c420 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
1c430 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
1c440 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
1c450 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
1c460 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
1c470 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
1c480 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
1c490 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
1c4a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
1c4b0 65 20 6f 66 20 61 20 5b 70 61 72 61 6d 65 74 65  e of a [paramete
1c4c0 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
1c4d0 65 72 5d 20 69 6e 20 74 68 65 20 57 48 45 52 45  er] in the WHERE
1c4e0 20 63 6c 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a   clause might.**
1c4f0 20 63 68 61 6e 67 65 20 74 68 65 20 71 75 65 72   change the quer
1c500 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
1c510 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  tement, then the
1c520 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79 20 62   statement may b
1c530 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1c540 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 20 28 61  ly recompiled (a
1c550 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
1c560 65 65 6e 20 61 20 73 63 68 65 6d 61 20 63 68 61  een a schema cha
1c570 6e 67 65 29 20 6f 6e 20 74 68 65 20 66 69 72 73  nge) on the firs
1c580 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  t .** [sqlite3_s
1c590 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
1c5a0 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
1c5b0 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   to the .** [sql
1c5c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
1c5d0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
1c5e0 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  e [parameter]. .
1c5f0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
1c600 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
1c610 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
1c620 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1c630 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1c640 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1c650 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1c660 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1c670 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1c680 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1c690 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1c6a0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1c6b0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1c6c0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1c6d0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1c6e0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1c6f0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1c700 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1c710 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1c720 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1c730 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1c740 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1c750 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
1c760 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1c770 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1c780 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1c790 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1c7a0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1c7b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1c7c0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1c7d0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1c7e0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1c7f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1c800 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1c810 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1c820 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1c830 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1c840 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1c850 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1c860 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1c870 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1c880 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1c890 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1c8a0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
1c8b0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1c8c0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1c8d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1c8e0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1c8f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1c900 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1c910 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1c920 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1c930 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1c940 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1c950 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1c960 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1c970 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1c980 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1c990 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1c9a0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1c9b0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1c9c0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1c9d0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1c9e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
1c9f0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1ca00 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1ca10 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1ca20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1ca30 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1ca40 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1ca50 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1ca60 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1ca70 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1ca80 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1ca90 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1caa0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1cab0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1cac0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1cad0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1cae0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1caf0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1cb00 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1cb10 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
1cb20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1cb30 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
1cb40 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
1cb50 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
1cb60 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
1cb70 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
1cb80 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
1cb90 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
1cba0 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
1cbb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1cbc0 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
1cbd0 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
1cbe0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1cbf0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1cc00 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
1cc10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1cc20 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  v2()]..*/.const 
1cc30 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
1cc40 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
1cc50 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1cc60 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
1cc70 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
1cc80 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
1cc90 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
1cca0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
1ccb0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1ccc0 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
1ccd0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
1cce0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1ccf0 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
1cd00 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
1cd10 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
1cd20 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
1cd30 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
1cd40 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
1cd50 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
1cd60 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
1cd70 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
1cd80 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
1cd90 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
1cda0 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
1cdb0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
1cdc0 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
1cdd0 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
1cde0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
1cdf0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
1ce00 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
1ce10 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
1ce20 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
1ce30 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
1ce40 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
1ce50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
1ce60 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
1ce70 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
1ce80 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
1ce90 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
1cea0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1ceb0 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
1cec0 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
1ced0 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
1cee0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
1cef0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
1cf00 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
1cf10 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
1cf20 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
1cf30 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
1cf40 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
1cf50 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
1cf60 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
1cf70 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
1cf80 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72  s held.  A inter
1cf90 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
1cfa0 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
1cfb0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1cfc0 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
1cfd0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1cfe0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1cff0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1d000 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
1d010 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
1d020 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
1d030 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
1d040 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1d050 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
1d060 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
1d070 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
1d080 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
1d090 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
1d0a0 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
1d0b0 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
1d0c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
1d0d0 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
1d0e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
1d0f0 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
1d100 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
1d110 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
1d120 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1d130 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1d140 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1d150 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
1d160 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
1d170 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
1d180 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
1d190 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
1d1a0 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
1d1b0 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
1d1c0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
1d1d0 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
1d1e0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65  ction between be
1d1f0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
1d200 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
1d210 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1d220 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
1d230 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
1d240 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1d250 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
1d260 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
1d270 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
1d280 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
1d290 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
1d2a0 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
1d2b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1d2c0 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
1d2d0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
1d2e0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1d2f0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
1d300 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
1d310 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
1d320 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
1d330 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
1d340 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1d350 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
1d360 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
1d370 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
1d380 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
1d390 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
1d3a0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
1d3b0 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
1d3c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
1d3d0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
1d3e0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
1d3f0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
1d400 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1d410 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
1d420 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
1d430 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
1d440 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
1d450 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
1d460 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
1d470 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
1d480 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
1d490 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
1d4a0 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
1d4b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
1d4c0 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
1d4d0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
1d4e0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
1d4f0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
1d500 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1d510 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
1d520 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
1d530 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
1d540 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1d550 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
1d560 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
1d570 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
1d580 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
1d590 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
1d5a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
1d5b0 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
1d5c0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
1d5d0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
1d5e0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
1d5f0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
1d600 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
1d610 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
1d620 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
1d630 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
1d640 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
1d650 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
1d660 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1d670 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
1d680 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
1d690 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d6a0 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
1d6b0 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
1d6c0 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
1d6d0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
1d6e0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
1d6f0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
1d700 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
1d710 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
1d720 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
1d730 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
1d740 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
1d750 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
1d760 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1d770 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1d780 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d790 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
1d7a0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
1d7b0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
1d7c0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
1d7d0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
1d7e0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
1d7f0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
1d800 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
1d810 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
1d820 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
1d830 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
1d840 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
1d850 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
1d860 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
1d870 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
1d880 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
1d890 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
1d8a0 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
1d8b0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
1d8c0 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
1d8d0 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
1d8e0 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
1d8f0 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
1d900 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
1d910 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
1d920 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
1d930 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1d940 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1d950 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
1d960 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
1d970 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
1d980 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1d990 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
1d9a0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
1d9b0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1d9c0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
1d9d0 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
1d9e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
1d9f0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
1da00 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
1da10 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
1da20 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
1da30 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
1da40 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
1da50 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
1da60 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
1da70 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
1da80 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
1da90 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
1daa0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
1dab0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
1dac0 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
1dad0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
1dae0 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
1daf0 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
1db00 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
1db10 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
1db20 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
1db30 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
1db40 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
1db50 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1db60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1db70 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
1db80 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
1db90 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
1dba0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
1dbb0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
1dbc0 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
1dbd0 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
1dbe0 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
1dbf0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
1dc00 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
1dc10 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
1dc20 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
1dc30 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
1dc40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
1dc50 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
1dc60 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
1dc70 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
1dc80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  r..**.** ^(In th
1dc90 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ose routines tha
1dca0 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20  t have a fourth 
1dcb0 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61  argument, its va
1dcc0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
1dcd0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
1dce0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20   the parameter. 
1dcf0 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68   To be clear: th
1dd00 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  e value is the.*
1dd10 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62  * number of <u>b
1dd20 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20  ytes</u> in the 
1dd30 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e  value, not the n
1dd40 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
1dd50 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68  ers.)^.** ^If th
1dd60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1dd70 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
1dd80 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
1dd90 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
1dda0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1ddb0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
1ddc0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
1ddd0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  or..**.** ^The f
1dde0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
1ddf0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
1de00 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
1de10 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
1de20 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
1de30 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
1de40 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
1de50 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
1de60 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
1de70 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
1de80 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1de90 69 74 2e 20 5e 49 66 20 74 68 65 20 66 69 66 74  it. ^If the fift
1dea0 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
1deb0 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
1dec0 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
1ded0 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
1dee0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
1def0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
1df00 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
1df10 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
1df20 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
1df30 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
1df40 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
1df50 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
1df60 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
1df70 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
1df80 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
1df90 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
1dfa0 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
1dfb0 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
1dfc0 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
1dfd0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
1dfe0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
1dff0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1e000 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72  ind_zeroblob() r
1e010 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42  outine binds a B
1e020 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20  LOB of length N 
1e030 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65  that.** is fille
1e040 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20  d with zeroes.  
1e050 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73  ^A zeroblob uses
1e060 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20   a fixed amount 
1e070 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75  of memory.** (ju
1e080 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f  st an integer to
1e090 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20   hold its size) 
1e0a0 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e  while it is bein
1e0b0 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20  g processed..** 
1e0c0 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e  Zeroblobs are in
1e0d0 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20  tended to serve 
1e0e0 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  as placeholders 
1e0f0 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a  for BLOBs whose.
1e100 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61  ** content is la
1e110 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e  ter written usin
1e120 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c  g.** [sqlite3_bl
1e130 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d  ob_open | increm
1e140 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20  ental BLOB I/O] 
1e150 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20  routines..** ^A 
1e160 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66  negative value f
1e170 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20  or the zeroblob 
1e180 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72  results in a zer
1e190 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a  o-length BLOB..*
1e1a0 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20  *.** ^If any of 
1e1b0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1e1c0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  _*() routines ar
1e1d0 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  e called with a 
1e1e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1e1f0 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  for the [prepare
1e200 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20  d statement] or 
1e210 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20  with a prepared 
1e220 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68  statement for wh
1e230 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
1e240 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e  step()] has been
1e250 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63   called more rec
1e260 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69  ently than [sqli
1e270 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a  te3_reset()],.**
1e280 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77   then the call w
1e290 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
1e2a0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20  TE_MISUSE].  If 
1e2b0 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  any sqlite3_bind
1e2c0 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69  _().** routine i
1e2d0 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70  s passed a [prep
1e2e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e2f0 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69  that has been fi
1e300 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20  nalized, the.** 
1e310 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
1e320 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
1e330 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20   harmful..**.** 
1e340 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f  ^Bindings are no
1e350 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65  t cleared by the
1e360 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1e370 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e  )] routine..** ^
1e380 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65  Unbound paramete
1e390 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  rs are interpret
1e3a0 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ed as NULL..**.*
1e3b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1e3c0 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72  ind_* routines r
1e3d0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1e3e0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20  ] on success or 
1e3f0 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  an.** [error cod
1e400 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67  e] if anything g
1e410 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b  oes wrong..** ^[
1e420 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
1e430 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
1e440 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
1e450 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
1e460 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
1e470 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
1e480 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
1e490 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
1e4a0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1e4b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
1e4c0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
1e4d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1e4e0 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
1e4f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1e500 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1e510 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1e520 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
1e530 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
1e540 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
1e550 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
1e560 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1e570 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
1e580 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
1e590 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
1e5a0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
1e5b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1e5c0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
1e5d0 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
1e5e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1e5f0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
1e600 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1e610 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
1e620 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
1e630 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1e640 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
1e650 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
1e660 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
1e670 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
1e680 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1e690 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
1e6a0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
1e6b0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
1e6c0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
1e6d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
1e6e0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
1e6f0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
1e700 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
1e710 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
1e720 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
1e730 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
1e740 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1e750 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
1e760 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  L Parameters.**.
1e770 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1e780 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
1e790 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
1e7a0 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
1e7b0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
1e7c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e7d0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
1e7e0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
1e7f0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
1e800 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
1e810 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
1e820 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
1e830 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
1e840 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
1e850 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
1e860 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
1e870 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
1e880 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
1e890 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
1e8a0 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
1e8b0 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
1e8c0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
1e8d0 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
1e8e0 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
1e8f0 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
1e900 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
1e910 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
1e920 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
1e930 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
1e940 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
1e950 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
1e960 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
1e970 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
1e980 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
1e990 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
1e9a0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
1e9b0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
1e9c0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
1e9d0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1e9e0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
1e9f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1ea00 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1ea10 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  x()]..*/.int sql
1ea20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1ea30 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ter_count(sqlite
1ea40 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
1ea50 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20   CAPI3REF: Name 
1ea60 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65  Of A Host Parame
1ea70 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ter.**.** ^The s
1ea80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1ea90 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
1eaa0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
1eab0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
1eac0 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
1ead0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
1eae0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1eaf0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
1eb00 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
1eb10 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
1eb20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
1eb30 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
1eb40 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
1eb50 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
1eb60 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
1eb70 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
1eb80 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
1eb90 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
1eba0 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
1ebb0 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
1ebc0 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
1ebd0 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
1ebe0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
1ebf0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
1ec00 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
1ec10 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
1ec20 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
1ec30 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
1ec40 61 6e 64 20 61 72 65 20 61 6c 73 6f 20 72 65 66  and are also ref
1ec50 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
1ec60 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
1ec70 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
1ec80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1ec90 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
1eca0 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
1ecb0 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
1ecc0 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
1ecd0 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
1ece0 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
1ecf0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1ed00 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
1ed10 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
1ed20 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
1ed30 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
1ed40 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
1ed50 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
1ed60 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
1ed70 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
1ed80 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
1ed90 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
1eda0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1edb0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1edc0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1edd0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1ede0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
1edf0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
1ee00 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
1ee10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1ee20 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
1ee30 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1ee40 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1ee50 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
1ee60 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  r *sqlite3_bind_
1ee70 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73  parameter_name(s
1ee80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1ee90 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1eea0 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20  REF: Index Of A 
1eeb0 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41  Parameter With A
1eec0 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a   Given Name.**.*
1eed0 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e  * ^Return the in
1eee0 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61  dex of an SQL pa
1eef0 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74  rameter given it
1ef00 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a  s name.  ^The.**
1ef10 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74   index value ret
1ef20 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c  urned is suitabl
1ef30 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65  e for use as the
1ef40 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d   second.** param
1ef50 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
1ef60 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
1ef70 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20  e3_bind()].  ^A 
1ef80 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72  zero.** is retur
1ef90 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69  ned if no matchi
1efa0 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ng parameter is 
1efb0 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72  found.  ^The par
1efc0 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d  ameter.** name m
1efd0 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20  ust be given in 
1efe0 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68  UTF-8 even if th
1eff0 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65  e original state
1f000 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70  ment.** was prep
1f010 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36  ared from UTF-16
1f020 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c   text using [sql
1f030 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1f040 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
1f050 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
1f060 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
1f070 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
1f080 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1f090 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
1f0a0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1f0b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1f0c0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  dex()]..*/.int s
1f0d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1f0e0 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69  meter_index(sqli
1f0f0 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74  te3_stmt*, const
1f100 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a   char *zName);..
1f110 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f120 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e  Reset All Bindin
1f130 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64  gs On A Prepared
1f140 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
1f150 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
1f160 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
1f170 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
1f180 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
1f190 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
1f1a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
1f1b0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
1f1c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f1d0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
1f1e0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
1f1f0 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
1f200 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
1f210 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1f220 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
1f230 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
1f240 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f250 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
1f260 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
1f270 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  et.**.** ^Return
1f280 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1f290 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
1f2a0 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65  sult set returne
1f2b0 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65  d by the.** [pre
1f2c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f2d0 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  . ^This routine 
1f2e0 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74  returns 0 if pSt
1f2f0 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20  mt is an SQL.** 
1f300 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64  statement that d
1f310 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64  oes not return d
1f320 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ata (for example
1f330 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a   an [UPDATE])..*
1f340 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
1f350 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74  lumn_count(sqlit
1f360 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1f370 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f380 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49  : Column Names I
1f390 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
1f3a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1f3b0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
1f3c0 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f  name assigned to
1f3d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f   a particular co
1f3e0 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72  lumn.** in the r
1f3f0 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b  esult set of a [
1f400 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
1f410 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  t.  ^The sqlite3
1f420 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a  _column_name().*
1f430 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
1f440 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1f450 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1f460 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a  ed UTF-8 string.
1f470 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
1f480 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72  olumn_name16() r
1f490 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1f4a0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
1f4b0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
1f4c0 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69  string.  ^The fi
1f4d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1f4e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1f4f0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61  tatement].** tha
1f500 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
1f510 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1f520 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ent. ^The second
1f530 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1f540 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  e.** column numb
1f550 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f  er.  ^The leftmo
1f560 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d  st column is num
1f570 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ber 0..**.** ^Th
1f580 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
1f590 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c  g pointer is val
1f5a0 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20  id until either 
1f5b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1f5c0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64  atement].** is d
1f5d0 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c  estroyed by [sql
1f5e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
1f5f0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
1f600 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
1f610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
1f620 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
1f630 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
1f640 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
1f650 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
1f660 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
1f670 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
1f680 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
1f690 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
1f6a0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
1f6b0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
1f6c0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
1f6d0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
1f6e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
1f6f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1f700 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
1f710 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
1f720 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
1f730 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
1f740 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
1f750 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
1f760 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
1f770 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
1f780 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
1f790 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
1f7a0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
1f7b0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
1f7c0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
1f7d0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
1f7e0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
1f7f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1f800 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
1f810 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
1f820 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
1f830 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
1f840 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
1f850 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
1f860 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f870 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
1f880 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
1f890 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
1f8a0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
1f8b0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
1f8c0 6d 69 6e 65 20 77 68 61 74 20 63 6f 6c 75 6d 6e  mine what column
1f8d0 20 6f 66 20 77 68 61 74 0a 2a 2a 20 74 61 62 6c   of what.** tabl
1f8e0 65 20 69 6e 20 77 68 69 63 68 20 64 61 74 61 62  e in which datab
1f8f0 61 73 65 20 61 20 72 65 73 75 6c 74 20 6f 66 20  ase a result of 
1f900 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
1f910 6d 65 6e 74 20 63 6f 6d 65 73 20 66 72 6f 6d 2e  ment comes from.
1f920 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
1f930 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72   the database or
1f940 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e   table or column
1f950 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64   can be returned
1f960 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20   as.** either a 
1f970 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
1f980 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64  string.  ^The _d
1f990 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65  atabase_ routine
1f9a0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20  s return.** the 
1f9b0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74  database name, t
1f9c0 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69  he _table_ routi
1f9d0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74  nes return the t
1f9e0 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a  able name, and.*
1f9f0 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f  * the origin_ ro
1fa00 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
1fa10 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a  e column name..*
1fa20 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
1fa30 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20  string is valid 
1fa40 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61  until the [prepa
1fa50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
1fa60 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75  s destroyed.** u
1fa70 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1fa80 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
1fa90 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
1faa0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
1fab0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
1fac0 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
1fad0 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
1fae0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
1faf0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
1fb00 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
1fb10 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
1fb20 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
1fb30 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
1fb40 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1fb50 65 6e 74 20 74 68 65 73 65 20 69 6e 74 65 72 66  ent these interf
1fb60 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
1fb70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
1fb80 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
1fb90 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
1fba0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
1fbb0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
1fbc0 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
1fbd0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
1fbe0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
1fbf0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
1fc00 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
1fc10 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
1fc20 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
1fc30 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  e interface..**.
1fc40 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
1fc50 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
1fc60 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
1fc70 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
1fc80 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
1fc90 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
1fca0 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
1fcb0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
1fcc0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
1fcd0 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
1fce0 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
1fcf0 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
1fd00 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1fd10 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
1fd20 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
1fd30 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
1fd40 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
1fd50 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1fd60 2c 20 74 61 62 6c 65 0a 2a 2a 20 6f 72 20 63 6f  , table.** or co
1fd70 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
1fd80 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
1fd90 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
1fda0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
1fdb0 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
1fdc0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 70 6f  e APIs, those po
1fdd0 73 74 66 69 78 65 64 20 77 69 74 68 20 22 31 36  stfixed with "16
1fde0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
1fdf0 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
1fe00 67 73 2c 20 74 68 65 20 6f 74 68 65 72 20 66 75  gs, the other fu
1fe10 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
1fe20 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
1fe30 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
1fe40 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
1fe50 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
1fe60 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
1fe70 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
1fe80 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
1fe90 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
1fea0 72 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64  r symbol defined
1feb0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
1fec0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
1fed0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
1fee0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1fef0 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
1ff00 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
1ff10 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
1ff20 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
1ff30 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
1ff40 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
1ff50 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
1ff60 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
1ff70 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
1ff80 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
1ff90 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
1ffa0 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
1ffb0 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
1ffc0 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
1ffd0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
1ffe0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
1fff0 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
20000 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
20010 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
20020 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
20030 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
20040 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
20050 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
20060 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
20070 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
20080 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
20090 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
200a0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
200b0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
200c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
200d0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
200e0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
200f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
20100 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36  umn_table_name16
20110 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
20120 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
20130 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20140 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
20150 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
20160 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
20170 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69  te3_column_origi
20180 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
20190 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
201a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
201b0 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20  clared Datatype 
201c0 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  Of A Query Resul
201d0 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
201e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
201f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
20200 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
20210 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
20220 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
20230 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
20240 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
20250 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
20260 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
20270 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
20280 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
20290 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
202a0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
202b0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
202c0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
202d0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
202e0 74 75 72 6e 65 64 2e 29 20 20 5e 49 66 20 74 68  turned.)  ^If th
202f0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
20300 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
20310 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
20320 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
20330 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
20340 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
20350 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
20360 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
20370 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
20380 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
20390 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
203a0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
203b0 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
203c0 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
203d0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
203e0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
203f0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
20400 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
20410 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
20420 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
20430 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
20440 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
20450 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
20460 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
20470 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
20480 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
20490 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
204a0 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
204b0 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
204c0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
204d0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
204e0 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
204f0 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
20500 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
20510 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
20520 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
20530 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
20540 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
20550 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
20560 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
20570 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
20580 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
20590 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
205a0 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
205b0 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
205c0 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
205d0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
205e0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
205f0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
20600 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
20610 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
20620 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73   values..*/.cons
20630 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
20640 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
20650 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
20660 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
20670 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
20680 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
20690 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
206a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
206b0 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
206c0 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41  tatement.**.** A
206d0 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
206e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
206f0 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
20700 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
20710 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20720 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
20730 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
20740 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
20750 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
20760 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
20770 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
20780 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
20790 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
207a0 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
207b0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
207c0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
207d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
207e0 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
207f0 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
20800 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
20810 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
20820 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
20830 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
20840 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
20850 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
20860 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
20870 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
20880 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
20890 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
208a0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
208b0 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
208c0 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
208d0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
208e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
208f0 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
20900 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
20910 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
20920 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
20930 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
20940 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
20950 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
20960 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
20970 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
20980 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79  * ^In the legacy
20990 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
209a0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
209b0 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
209c0 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53  ITE_BUSY],.** [S
209d0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
209e0 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
209f0 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
20a00 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
20a10 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22  * ^With the "v2"
20a20 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
20a30 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65  of the other [re
20a40 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a  sult codes] or.*
20a50 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
20a60 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20  lt codes] might 
20a70 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77  be returned as w
20a80 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ell..**.** ^[SQL
20a90 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
20aa0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
20ab0 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
20ac0 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
20ad0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
20ae0 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
20af0 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49   do its job.  ^I
20b00 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
20b10 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a  is a [COMMIT].**
20b20 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69   or occurs outsi
20b30 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69  de of an explici
20b40 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
20b50 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72  hen you can retr
20b60 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  y the.** stateme
20b70 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  nt.  If the stat
20b80 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b  ement is not a [
20b90 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75  COMMIT] and occu
20ba0 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65  rs within a.** e
20bb0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
20bc0 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
20bd0 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
20be0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
20bf0 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
20c00 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
20c10 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
20c20 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
20c30 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
20c40 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
20c50 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
20c60 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
20c70 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
20c80 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
20c90 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
20ca0 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
20cb0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
20cc0 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
20cd0 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
20ce0 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
20cf0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
20d00 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
20d10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
20d20 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
20d30 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
20d40 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
20d50 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
20d60 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
20d70 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
20d80 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
20d90 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
20da0 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
20db0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
20dc0 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
20dd0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
20de0 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
20df0 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
20e00 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
20e10 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
20e20 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
20e30 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
20e40 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
20e50 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
20e60 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
20e70 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
20e80 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
20e90 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
20ea0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
20eb0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
20ec0 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
20ed0 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
20ee0 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
20ef0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
20f00 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
20f10 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
20f20 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
20f30 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
20f40 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
20f50 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
20f60 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
20f70 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
20f80 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
20f90 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
20fa0 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
20fb0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
20fc0 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
20fd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20fe0 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
20ff0 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
21000 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
21010 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
21020 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
21030 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
21040 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
21050 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
21060 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
21070 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
21080 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
21090 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
210a0 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
210b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
210c0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
210d0 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
210e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
210f0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
21100 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
21110 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
21120 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
21130 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
21140 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
21150 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
21160 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
21170 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
21180 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
21190 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
211a0 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
211b0 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
211c0 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
211d0 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
211e0 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
211f0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
21200 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
21210 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
21220 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
21230 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
21240 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
21250 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
21260 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
21270 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
21280 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
21290 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
212a0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
212b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
212c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
212d0 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
212e0 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
212f0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
21300 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
21310 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
21320 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
21330 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
21340 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
21350 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
21360 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
21370 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
21380 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
21390 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
213a0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
213b0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
213c0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
213d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
213e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
213f0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
21400 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
21410 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
21420 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
21430 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
21440 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
21450 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
21460 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
21470 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
21480 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
21490 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
214a0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
214b0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
214c0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
214d0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
214e0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
214f0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
21500 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
21510 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
21520 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a  result set.**.**
21530 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
21540 74 61 5f 63 6f 75 6e 74 28 50 29 20 74 68 65 20  ta_count(P) the 
21550 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
21560 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6f 66 20 74  s in the.** of t
21570 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
21580 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
21590 6d 65 6e 74 5d 20 50 2e 0a 2a 2f 0a 69 6e 74 20  ment] P..*/.int 
215a0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
215b0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
215c0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
215d0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
215e0 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
215f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
21600 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
21610 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
21620 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
21630 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
21640 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
21650 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
21660 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
21670 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
21680 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
21690 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
216a0 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
216b0 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
216c0 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
216d0 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
216e0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
216f0 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
21700 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
21710 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
21720 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
21730 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
21740 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
21750 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
21760 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
21770 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
21780 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
21790 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
217a0 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
217b0 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
217c0 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
217d0 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
217e0 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
217f0 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
21800 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
21810 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
21820 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
21830 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
21840 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
21850 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
21860 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
21870 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
21880 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
21890 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
218a0 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
218b0 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
218c0 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
218d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
218e0 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
218f0 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
21900 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
21910 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
21920 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
21930 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
21940 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
21950 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
21960 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
21970 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
21980 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
21990 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
219a0 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
219b0 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
219c0 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
219d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
219e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
219f0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
21a00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
21a10 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
21a20 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
21a30 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
21a40 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
21a50 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
21a60 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
21a70 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
21a80 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
21a90 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
21aa0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
21ab0 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
21ac0 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
21ad0 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
21ae0 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
21af0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
21b00 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
21b10 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
21b20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
21b30 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
21b40 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
21b50 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
21b60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
21b70 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
21b80 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
21b90 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
21ba0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
21bb0 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
21bc0 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
21bd0 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
21be0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
21bf0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
21c00 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
21c10 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
21c20 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
21c30 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
21c40 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
21c50 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
21c60 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
21c70 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
21c80 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
21c90 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
21ca0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
21cb0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
21cc0 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
21cd0 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
21ce0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
21cf0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
21d00 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
21d10 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
21d20 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
21d30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21d40 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
21d50 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
21d60 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
21d70 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
21d80 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
21d90 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
21da0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
21db0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
21dc0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
21dd0 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
21de0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
21df0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
21e00 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
21e10 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
21e20 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
21e30 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
21e40 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
21e50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
21e60 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
21e70 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
21e80 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
21e90 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
21ea0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
21eb0 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
21ec0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
21ed0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
21ee0 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
21ef0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
21f00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
21f10 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
21f20 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
21f30 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
21f40 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
21f50 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
21f60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
21f70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
21f80 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
21f90 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
21fa0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
21fb0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
21fc0 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
21fd0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
21fe0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
21ff0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
22000 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
22010 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
22020 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
22030 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
22040 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
22050 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
22060 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
22070 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
22080 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
22090 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
220a0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
220b0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
220c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
220d0 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
220e0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
220f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
22100 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
22110 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
22120 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
22130 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
22140 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
22150 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
22160 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
22170 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
22180 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
22190 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
221a0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
221b0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
221c0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
221d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
221e0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
221f0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
22200 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
22210 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
22220 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
22230 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
22240 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
22250 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 54 68 65 20  string..** ^The 
22260 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 64  value returned d
22270 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
22280 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
22290 74 6f 72 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  tor at the end.*
222a0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
222b0 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
222c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
222d0 65 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ed is the number
222e0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
222f0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
22300 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
22310 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
22320 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
22330 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
22340 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
22350 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
22360 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
22370 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
22380 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
22390 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
223a0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
223b0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
223c0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
223d0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
223e0 4f 42 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  OB is an arbitra
223f0 72 79 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 70  ry.** pointer, p
22400 6f 73 73 69 62 6c 79 20 65 76 65 6e 20 61 20 4e  ossibly even a N
22410 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
22420 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
22430 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
22440 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
22450 6c 61 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lar to sqlite3_c
22460 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
22470 20 62 75 74 20 6c 65 61 76 65 73 20 74 68 65 20   but leaves the 
22480 72 65 73 75 6c 74 20 69 6e 20 55 54 46 2d 31 36  result in UTF-16
22490 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
224a0 6f 72 64 65 72 20 69 6e 73 74 65 61 64 20 6f 66  order instead of
224b0 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 54 68 65 20   UTF-8..** ^The 
224c0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
224d0 69 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 64 20  is not included 
224e0 69 6e 20 74 68 69 73 20 63 6f 75 6e 74 2e 0a 2a  in this count..*
224f0 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
22500 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
22510 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
22520 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
22530 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
22540 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
22550 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
22560 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
22570 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
22580 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
22590 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
225a0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
225b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
225c0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
225d0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
225e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
225f0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
22600 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
22610 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
22620 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
22630 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
22640 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
22650 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
22660 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
22670 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
22680 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
22690 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
226a0 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
226b0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
226c0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
226d0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
226e0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
226f0 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
22700 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
22710 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
22720 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
22730 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
22740 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
22750 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
22760 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
22770 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
22780 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
22790 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
227a0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
227b0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
227c0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
227d0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
227e0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
227f0 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
22800 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
22810 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
22820 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
22830 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
22840 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
22850 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
22860 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
22870 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
22880 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
22890 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
228a0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
228b0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
228c0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
228d0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
228e0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
228f0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
22900 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
22910 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
22920 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
22930 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
22940 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
22950 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
22960 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
22970 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
22980 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
22990 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
229a0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
229b0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
229c0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
229d0 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
229e0 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
229f0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
22a00 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
22a10 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
22a20 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
22a30 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
22a40 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
22a50 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
22a60 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
22a70 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
22a80 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
22a90 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
22aa0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
22ab0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
22ac0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
22ad0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
22ae0 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
22af0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
22b00 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
22b10 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
22b20 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
22b30 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
22b40 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
22b50 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
22b60 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
22b70 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
22b80 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
22b90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
22ba0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
22bb0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
22bc0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
22bd0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
22be0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
22bf0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
22c00 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
22c10 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
22c20 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
22c30 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
22c40 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
22c50 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
22c60 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
22c70 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
22c80 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
22c90 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
22ca0 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
22cb0 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
22cc0 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
22cd0 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
22ce0 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
22cf0 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
22d00 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
22d10 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
22d20 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
22d30 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
22d40 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
22d50 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
22d60 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
22d70 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
22d80 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
22d90 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
22da0 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
22db0 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
22dc0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
22dd0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
22de0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
22df0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
22e00 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
22e10 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
22e20 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
22e30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
22e40 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
22e50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
22e60 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
22e70 69 64 61 74 65 64 2e 0a 2a 2a 20 5e 28 54 79 70  idated..** ^(Typ
22e80 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
22e90 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
22ea0 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
22eb0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
22ec0 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
22ed0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
22ee0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
22ef0 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
22f00 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
22f10 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
22f20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
22f30 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
22f40 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
22f50 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
22f60 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
22f70 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
22f80 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
22f90 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
22fa0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
22fb0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
22fc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
22fd0 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
22fe0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22ff0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
23000 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
23010 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
23020 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
23030 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
23040 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
23050 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
23060 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
23070 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
23080 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
23090 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
230a0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
230b0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
230c0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
230d0 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
230e0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  >.** </ul>)^.**.
230f0 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20  ** ^Conversions 
23100 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65  between UTF-16be
23110 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72   and UTF-16le ar
23120 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e  e always done in
23130 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a   place and do.**
23140 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20   not invalidate 
23150 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c  a prior pointer,
23160 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
23170 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  e the content of
23180 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74   the buffer.** t
23190 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f  hat the prior po
231a0 69 6e 74 65 72 20 70 6f 69 6e 74 73 20 74 6f 20  inter points to 
231b0 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
231c0 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
231d0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
231e0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
231f0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
23200 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
23210 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
23220 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
23230 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
23240 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
23250 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
23260 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  idated..**.** ^(
23270 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
23280 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
23290 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
232a0 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
232b0 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
232c0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
232d0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
232e0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
232f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
23300 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
23310 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
23320 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
23330 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23340 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
23350 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
23360 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
23370 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
23380 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
23390 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
233a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
233b0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
233c0 29 5e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  )^.**.** In othe
233d0 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
233e0 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
233f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
23400 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
23410 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
23420 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
23430 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
23440 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
23450 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
23460 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
23470 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
23480 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
23490 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
234a0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
234b0 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
234c0 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
234d0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
234e0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
234f0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
23500 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
23510 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
23520 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
23530 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
23540 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
23550 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
23560 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
23570 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
23580 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23590 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
235a0 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
235b0 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
235c0 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
235d0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
235e0 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
235f0 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
23600 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
23610 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
23620 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
23630 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
23640 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
23650 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
23660 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
23670 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
23680 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
23690 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
236a0 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
236b0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
236c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
236d0 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
236e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
236f0 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
23700 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
23710 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
23720 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
23730 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
23740 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
23750 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
23760 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
23770 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
23780 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
23790 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
237a0 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
237b0 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
237c0 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
237d0 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
237e0 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
237f0 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
23800 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
23810 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
23820 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
23830 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
23840 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
23850 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
23860 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
23870 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
23880 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23890 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
238a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
238b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
238c0 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
238d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
238e0 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
238f0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
23900 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
23910 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
23920 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
23930 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
23940 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
23950 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
23960 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
23970 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23980 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
23990 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
239a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
239b0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
239c0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
239d0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
239e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
239f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23a00 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
23a10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
23a20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
23a30 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
23a40 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
23a50 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
23a60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23a70 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
23a80 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
23a90 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
23aa0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
23ab0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23ac0 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
23ad0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
23ae0 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
23af0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
23b00 2a 2a 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  ** ^If the state
23b10 6d 65 6e 74 20 77 61 73 20 65 78 65 63 75 74 65  ment was execute
23b20 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  d successfully o
23b30 72 20 6e 6f 74 20 65 78 65 63 75 74 65 64 20 61  r not executed a
23b40 74 20 61 6c 6c 2c 20 74 68 65 6e 0a 2a 2a 20 53  t all, then.** S
23b50 51 4c 49 54 45 5f 4f 4b 20 69 73 20 72 65 74 75  QLITE_OK is retu
23b60 72 6e 65 64 2e 20 5e 49 66 20 65 78 65 63 75 74  rned. ^If execut
23b70 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
23b80 6d 65 6e 74 20 66 61 69 6c 65 64 20 74 68 65 6e  ment failed then
23b90 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
23ba0 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  de] or [extended
23bb0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
23bc0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
23bd0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
23be0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
23bf0 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 20  ny point during 
23c00 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
23c10 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
23c20 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
23c30 49 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 6d  If the virtual m
23c40 61 63 68 69 6e 65 20 68 61 73 20 6e 6f 74 0a 2a  achine has not.*
23c50 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
23c60 75 74 69 6f 6e 20 77 68 65 6e 20 74 68 69 73 20  ution when this 
23c70 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
23c80 64 2c 20 74 68 61 74 20 69 73 20 6c 69 6b 65 0a  d, that is like.
23c90 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  ** encountering 
23ca0 61 6e 20 65 72 72 6f 72 20 6f 72 20 61 6e 20 5b  an error or an [
23cb0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
23cc0 74 20 7c 20 69 6e 74 65 72 72 75 70 74 5d 2e 0a  t | interrupt]..
23cd0 2a 2a 20 5e 49 6e 63 6f 6d 70 6c 65 74 65 20 75  ** ^Incomplete u
23ce0 70 64 61 74 65 73 20 6d 61 79 20 62 65 20 72 6f  pdates may be ro
23cf0 6c 6c 65 64 20 62 61 63 6b 20 61 6e 64 20 74 72  lled back and tr
23d00 61 6e 73 61 63 74 69 6f 6e 73 20 63 61 6e 63 65  ansactions cance
23d10 6c 65 64 2c 0a 2a 2a 20 64 65 70 65 6e 64 69 6e  led,.** dependin
23d20 67 20 6f 6e 20 74 68 65 20 63 69 72 63 75 6d 73  g on the circums
23d30 74 61 6e 63 65 73 2c 20 61 6e 64 20 74 68 65 0a  tances, and the.
23d40 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
23d50 72 65 74 75 72 6e 65 64 20 77 69 6c 6c 20 62 65  returned will be
23d60 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
23d70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23d80 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
23d90 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
23da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23db0 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
23dc0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
23dd0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
23de0 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
23df0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
23e00 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
23e10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
23e20 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
23e30 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
23e40 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
23e50 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
23e60 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
23e70 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
23e80 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
23e90 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
23ea0 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
23eb0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
23ec0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
23ed0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
23ee0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
23ef0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
23f00 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
23f10 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
23f20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
23f30 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
23f40 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
23f50 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23f60 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
23f70 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
23f80 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
23f90 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
23fa0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
23fb0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
23fc0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
23fd0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
23fe0 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
23ff0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
24000 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
24010 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
24020 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
24030 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
24040 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
24050 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
24060 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
24070 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
24080 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
24090 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
240a0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
240b0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
240c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
240d0 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
240e0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
240f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
24100 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
24110 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
24120 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
24130 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
24140 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
24150 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
24160 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
24170 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
24180 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
24190 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
241a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
241b0 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  S..*/.int sqlite
241c0 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
241d0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
241e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
241f0 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
24200 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
24210 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
24220 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
24230 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
24240 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
24250 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
24260 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
24270 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
24280 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
24290 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
242a0 20 5e 54 68 65 73 65 20 74 77 6f 20 66 75 6e 63   ^These two func
242b0 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
242c0 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
242d0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
242e0 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
242f0 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
24300 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
24310 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
24320 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
24330 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
24340 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
24350 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
24360 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
24370 65 72 65 6e 63 65 20 62 65 74 77 65 65 6e 20 74  erence between t
24380 68 65 0a 2a 2a 20 74 77 6f 20 69 73 20 74 68 61  he.** two is tha
24390 74 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  t the second par
243a0 61 6d 65 74 65 72 2c 20 74 68 65 20 6e 61 6d 65  ameter, the name
243b0 20 6f 66 20 74 68 65 20 28 73 63 61 6c 61 72 29   of the (scalar)
243c0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
243d0 61 67 67 72 65 67 61 74 65 2c 20 69 73 20 65 6e  aggregate, is en
243e0 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 20 66  coded in UTF-8 f
243f0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
24400 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 61 6e 64  e_function() and
24410 20 55 54 46 2d 31 36 0a 2a 2a 20 66 6f 72 20 73   UTF-16.** for s
24420 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
24430 6e 63 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 0a 2a  nction16()..**.*
24440 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
24450 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
24460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24470 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
24480 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
24490 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
244a0 20 5e 49 66 20 61 20 73 69 6e 67 6c 65 20 70 72   ^If a single pr
244b0 6f 67 72 61 6d 20 75 73 65 73 20 6d 6f 72 65 20  ogram uses more 
244c0 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
244d0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
244e0 69 6e 74 65 72 6e 61 6c 6c 79 2c 20 74 68 65 6e  internally, then
244f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
24500 75 73 74 20 62 65 20 61 64 64 65 64 20 69 6e 64  ust be added ind
24510 69 76 69 64 75 61 6c 6c 79 20 74 6f 0a 2a 2a 20  ividually to.** 
24520 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
24530 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nnection..**.** 
24540 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
24550 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
24560 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
24570 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
24580 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
24590 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
245a0 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
245b0 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
245c0 79 74 65 73 2c 20 65 78 63 6c 75 73 69 76 65 20  ytes, exclusive 
245d0 6f 66 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74  of.** the zero-t
245e0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65  erminator.  Note
245f0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 20 6c   that the name l
24600 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
24610 6e 20 62 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20  n bytes, not.** 
24620 63 68 61 72 61 63 74 65 72 73 2e 20 20 5e 41 6e  characters.  ^An
24630 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
24640 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
24650 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
24660 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
24670 20 69 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f   in [SQLITE_ERRO
24680 52 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  R] being returne
24690 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
246a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
246b0 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
246c0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
246d0 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
246e0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
246f0 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
24700 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
24710 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
24720 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
24730 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
24740 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
24750 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
24760 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
24770 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
24780 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
24790 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
247a0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
247b0 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
247c0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
247d0 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
247e0 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
247f0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
24800 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
24810 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75  d..**.** The fou
24820 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
24830 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
24840 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
24850 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
24860 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
24870 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
24880 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
24890 72 61 6d 65 74 65 72 73 2e 20 20 41 6e 79 20 53  rameters.  Any S
248a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
248b0 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
248c0 64 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  d be able to wor
248d0 6b 0a 2a 2a 20 77 6f 72 6b 20 77 69 74 68 20 55  k.** work with U
248e0 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20  TF-8, UTF-16le, 
248f0 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75  or UTF-16be.  Bu
24900 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74  t some implement
24910 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a  ations may be.**
24920 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20   more efficient 
24930 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e  with one encodin
24940 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20  g than another. 
24950 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
24960 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73   may.** invoke s
24970 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
24980 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69  nction() or sqli
24990 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
249a0 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65  ion16() multiple
249b0 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74  .** times with t
249c0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
249d0 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72   but with differ
249e0 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54  ent values of eT
249f0 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e  extRep..** ^When
24a00 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
24a10 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
24a20 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61   same function a
24a30 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51  re available, SQ
24a40 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63  Lite.** will pic
24a50 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69  k the one that i
24a60 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73  nvolves the leas
24a70 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61  t amount of data
24a80 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20   conversion..** 
24a90 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79  If there is only
24aa0 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d   a single implem
24ab0 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64  entation which d
24ac0 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61  oes not care wha
24ad0 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69  t text.** encodi
24ae0 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  ng is used, then
24af0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
24b00 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b  ment should be [
24b10 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a  SQLITE_ANY]..**.
24b20 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70  ** ^(The fifth p
24b30 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61  arameter is an a
24b40 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72  rbitrary pointer
24b50 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74  .  The implement
24b60 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ation of the.** 
24b70 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69  function can gai
24b80 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73  n access to this
24b90 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b   pointer using [
24ba0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
24bb0 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  a()].)^.**.** Th
24bc0 65 20 73 65 76 65 6e 74 68 2c 20 65 69 67 68 74  e seventh, eight
24bd0 68 20 61 6e 64 20 6e 69 6e 74 68 20 70 61 72 61  h and ninth para
24be0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
24bf0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
24c00 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
24c10 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
24c20 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
24c30 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
24c40 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
24c50 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
24c60 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
24c70 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
24c80 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
24c90 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
24ca0 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
24cb0 70 6f 69 6e 74 65 72 73 20 73 68 6f 75 6c 64 20  pointers should 
24cc0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
24cd0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
24ce0 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
24cf0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
24d00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
24d10 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
24d20 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
24d30 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
24d40 64 20 4e 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65  d NULL should be
24d50 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
24d60 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
24d70 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
24d80 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
24d90 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
24da0 4c 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  L for all three 
24db0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
24dc0 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ks..**.** ^It is
24dd0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
24de0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
24df0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
24e00 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
24e10 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
24e20 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
24e30 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
24e40 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
24e50 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
24e60 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
24e70 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
24e80 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
24e90 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
24ea0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
24eb0 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
24ec0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
24ed0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
24ee0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
24ef0 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
24f00 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
24f10 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
24f20 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
24f30 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
24f40 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
24f50 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
24f60 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
24f70 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
24f80 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
24f90 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
24fa0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
24fb0 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
24fc0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
24fd0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
24fe0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
24ff0 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
25000 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
25010 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
25020 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
25030 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
25040 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
25050 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
25060 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
25070 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
25080 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
25090 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
250a0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
250b0 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
250c0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
250d0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
250e0 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
250f0 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
25100 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
25110 63 74 69 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20  ctions..** ^The 
25120 66 69 72 73 74 20 61 70 70 6c 69 63 61 74 69 6f  first applicatio
25130 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
25140 6f 6e 20 77 69 74 68 20 61 20 67 69 76 65 6e 20  on with a given 
25150 6e 61 6d 65 20 6f 76 65 72 72 69 64 65 73 20 61  name overrides a
25160 6c 6c 0a 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66  ll.** built-in f
25170 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 65 20  unctions in the 
25180 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
25190 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 69 74 68 20  onnection] with 
251a0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a  the same name..*
251b0 2a 20 5e 53 75 62 73 65 71 75 65 6e 74 20 61 70  * ^Subsequent ap
251c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
251d0 64 20 66 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74  d functions of t
251e0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c  he same name onl
251f0 79 20 6f 76 65 72 72 69 64 65 20 0a 2a 2a 20 70  y override .** p
25200 72 69 6f 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  rior application
25210 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
25220 6e 73 20 74 68 61 74 20 61 72 65 20 61 6e 20 65  ns that are an e
25230 78 61 63 74 20 6d 61 74 63 68 20 66 6f 72 20 74  xact match for t
25240 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
25250 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 70  parameters and p
25260 72 65 66 65 72 72 65 64 20 65 6e 63 6f 64 69 6e  referred encodin
25270 67 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70  g..**.** ^An app
25280 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25290 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72   function is per
252a0 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f  mitted to call o
252b0 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
252c0 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65  nterfaces.  Howe
252d0 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20  ver, such calls 
252e0 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73  must not.** clos
252f0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
25300 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69  onnection nor fi
25310 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20  nalize or reset 
25320 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  the prepared.** 
25330 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69  statement in whi
25340 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ch the function 
25350 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69  is running..*/.i
25360 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
25370 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
25380 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
25390 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
253a0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
253b0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
253c0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
253d0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
253e0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
253f0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
25400 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
25410 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
25420 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
25430 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
25440 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
25450 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
25460 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
25470 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
25480 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
25490 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
254a0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
254b0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
254c0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
254d0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
254e0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
254f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
25500 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
25510 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
25520 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
25530 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
25540 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
25550 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
25560 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a  3_context*).);..
25570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25580 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
25590 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
255a0 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
255b0 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
255c0 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
255d0 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
255e0 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
255f0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
25600 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
25610 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
25620 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
25630 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
25640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
25650 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
25660 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
25670 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
25680 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
25690 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
256a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
256b0 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
256c0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
256d0 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20  e_function only 
256e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
256f0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
25700 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
25710 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
25720 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
25730 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
25740 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
25750 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
25760 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
25770 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
25780 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
25790 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
257a0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
257b0 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
257c0 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
257d0 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
257e0 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
257f0 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
25800 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
25810 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
25820 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
25830 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
25840 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
25850 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
25860 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
25870 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
25880 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
25890 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79  ll you what they
258a0 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
258b0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
258c0 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45  ECATED.SQLITE_DE
258d0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
258e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
258f0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
25900 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  text*);.SQLITE_D
25910 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
25920 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
25930 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
25940 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
25950 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
25960 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
25970 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
25980 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
25990 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
259a0 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
259b0 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
259c0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
259d0 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
259e0 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
259f0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
25a00 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
25a10 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
25a20 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
25a30 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
25a40 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
25a50 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
25a60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25a70 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
25a80 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
25a90 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
25aa0 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
25ab0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
25ac0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
25ad0 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
25ae0 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
25af0 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
25b00 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
25b10 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
25b20 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
25b30 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
25b40 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
25b50 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
25b60 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
25b70 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
25b80 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
25b90 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
25ba0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
25bb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
25bc0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
25bd0 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
25be0 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
25bf0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
25c00 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
25c10 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34  egates..** The 4
25c20 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
25c30 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
25c40 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
25c50 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
25c60 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
25c70 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
25c80 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
25c90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25ca0 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
25cb0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
25cc0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
25cd0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
25ce0 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
25cf0 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
25d00 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
25d10 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
25d20 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
25d30 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
25d40 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
25d50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
25d60 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
25d70 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
25d80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
25d90 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
25da0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
25db0 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
25dc0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
25dd0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
25de0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
25df0 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
25e00 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
25e10 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
25e20 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
25e30 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
25e40 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
25e50 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
25e60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
25e70 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
25e80 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
25e90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
25ea0 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
25eb0 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
25ec0 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
25ed0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
25ee0 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
25ef0 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
25f00 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
25f10 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
25f20 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
25f30 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
25f40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
25f50 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
25f60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
25f70 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
25f80 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
25f90 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
25fa0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
25fb0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
25fc0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
25fd0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
25fe0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
25ff0 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
26000 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
26010 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
26020 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
26030 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
26040 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
26050 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
26060 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
26070 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
26080 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
26090 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
260a0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
260b0 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
260c0 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
260d0 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
260e0 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
260f0 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
26100 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
26110 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
26120 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
26130 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
26140 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
26150 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
26160 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
26170 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
26180 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
26190 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
261a0 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
261b0 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
261c0 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
261d0 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
261e0 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
261f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
26200 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
26210 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
26220 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
26230 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
26240 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
26250 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
26260 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
26270 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
26280 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
26290 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
262a0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
262b0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
262c0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
262d0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
262e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
262f0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
26300 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
26310 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
26320 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
26330 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
26340 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
26350 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
26360 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
26370 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
26380 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
26390 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
263a0 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
263b0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
263c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
263d0 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
263e0 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
263f0 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
26400 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
26410 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
26420 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
26430 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
26440 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
26450 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
26460 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
26470 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
26480 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
26490 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
264a0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
264b0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
264c0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
264d0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
264e0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
264f0 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
26500 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
26510 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
26520 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
26530 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
26540 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
26550 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
26560 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
26570 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
26580 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
26590 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
265a0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
265b0 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
265c0 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
265d0 49 6d 70 6c 65 6d 65 6e 74 69 6f 6e 73 20 6f 66  Implementions of
265e0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
265f0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
26600 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
26610 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
26620 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
26630 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
26640 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
26650 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
26660 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
26670 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
26680 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
26690 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
266a0 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
266b0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
266c0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
266d0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
266e0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
266f0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
26700 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
26710 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
26720 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
26730 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
26740 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
26750 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
26760 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
26770 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
26780 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
26790 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
267a0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
267b0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
267c0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
267d0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
267e0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
267f0 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
26800 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
26810 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
26820 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
26830 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
26840 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
26850 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
26860 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
26870 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
26880 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
26890 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
268a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
268b0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
268c0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
268d0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
268e0 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
268f0 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
26900 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
26910 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
26920 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
26930 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
26940 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
26950 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26960 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
26970 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
26980 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
26990 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a  pointer if N is.
269a0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  ** less than or 
269b0 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
269c0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
269d0 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
269e0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
269f0 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
26a00 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
26a10 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
26a20 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
26a30 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
26a40 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
26a50 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
26a60 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
26a70 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
26a80 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
26a90 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
26aa0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
26ab0 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
26ac0 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
26ad0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
26ae0 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
26af0 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
26b00 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
26b10 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
26b20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
26b30 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
26b40 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
26b50 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
26b60 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
26b70 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
26b80 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
26b90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
26ba0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
26bb0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
26bc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
26bd0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
26be0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
26bf0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
26c00 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
26c10 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
26c20 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
26c30 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
26c40 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
26c50 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
26c60 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
26c70 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
26c80 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
26c90 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
26ca0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
26cb0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
26cc0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
26cd0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
26ce0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
26cf0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
26d00 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
26d10 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
26d20 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
26d30 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
26d40 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
26d50 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
26d60 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
26d70 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
26d80 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
26d90 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
26da0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
26db0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
26dc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
26dd0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
26de0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
26df0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
26e00 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
26e10 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
26e20 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
26e30 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
26e40 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
26e50 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
26e60 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
26e70 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
26e80 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
26e90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
26ea0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
26eb0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
26ec0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
26ed0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
26ee0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
26ef0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
26f00 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
26f10 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
26f20 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
26f30 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
26f40 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
26f50 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
26f60 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
26f70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
26f80 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
26f90 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
26fa0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
26fb0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
26fc0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
26fd0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26fe0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
26ff0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
27000 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
27010 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
27020 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
27030 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
27040 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
27050 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
27060 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
27070 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
27080 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
27090 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
270a0 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
270b0 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
270c0 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
270d0 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
270e0 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
270f0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
27100 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
27110 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
27120 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
27130 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
27140 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
27150 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
27160 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
27170 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
27180 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
27190 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
271a0 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
271b0 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
271c0 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
271d0 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
271e0 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
271f0 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
27200 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
27210 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
27220 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
27230 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
27240 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
27250 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
27260 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
27270 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
27280 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
27290 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
272a0 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
272b0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
272c0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
272d0 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
272e0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
272f0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
27300 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
27310 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
27320 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
27330 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
27340 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
27350 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
27360 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
27370 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
27380 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
27390 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
273a0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
273b0 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
273c0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
273d0 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
273e0 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
273f0 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
27400 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
27410 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
27420 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20  ^If no metadata 
27430 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a  has been ever.**
27440 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68   been set for th
27450 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f  e Nth argument o
27460 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
27470 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
27480 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  ponding.** funct
27490 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61  ion parameter ha
274a0 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
274b0 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
274c0 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73  s set,.** then s
274d0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
274e0 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  ta() returns a N
274f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
27500 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27510 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
27520 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
27530 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
27540 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
27550 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
27560 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
27570 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
27580 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
27590 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
275a0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
275b0 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
275c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
275d0 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
275e0 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
275f0 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
27600 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
27610 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  d..** ^If it is 
27620 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
27630 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
27640 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
27650 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
27660 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
27670 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
27680 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
27690 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
276a0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
276b0 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
276c0 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
276d0 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
276e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
276f0 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
27700 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
27710 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
27720 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
27730 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
27740 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
27750 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
27760 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
27770 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
27780 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e  ^The only guaran
27790 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74  tee is that.** t
277a0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
277b0 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  ll be called bef
277c0 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61  ore the metadata
277d0 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a   is dropped..**.
277e0 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65  ** ^(In practice
277f0 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
27800 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
27810 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
27820 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
27830 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
27840 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
27850 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
27860 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
27870 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
27880 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  ters].)^.**.** T
27890 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
278a0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
278b0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
278c0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
278d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
278e0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
278f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
27900 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
27910 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
27920 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
27930 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
27940 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
27950 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
27960 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
27970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
27980 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
27990 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
279a0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
279b0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
279c0 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
279d0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
279e0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
279f0 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
27a00 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
27a10 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
27a20 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
27a30 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
27a40 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
27a50 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
27a60 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
27a70 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
27a80 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
27a90 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
27aa0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
27ab0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
27ac0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
27ad0 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
27ae0 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
27af0 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
27b00 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
27b10 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
27b20 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
27b30 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
27b40 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
27b50 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
27b60 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
27b70 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
27b80 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
27b90 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
27ba0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
27bb0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
27bc0 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
27bd0 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20  compilers.  See 
27be0 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f  ticket #2191..*/
27bf0 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
27c00 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
27c10 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
27c20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27c30 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
27c40 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
27c50 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
27c60 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
27c70 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
27c80 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
27c90 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
27ca0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
27cb0 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
27cc0 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
27cd0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
27ce0 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
27cf0 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
27d00 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
27d10 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
27d20 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
27d30 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
27d40 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
27d50 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
27d60 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
27d70 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
27d80 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
27d90 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
27da0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
27db0 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
27dc0 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
27dd0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
27de0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
27df0 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
27e00 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
27e10 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
27e20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27e30 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
27e40 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
27e50 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
27e60 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
27e70 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
27e80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
27e90 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
27ea0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
27eb0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
27ec0 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
27ed0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
27ee0 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
27ef0 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
27f00 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
27f10 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
27f20 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
27f30 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
27f40 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
27f50 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
27f60 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
27f70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
27f80 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
27f90 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
27fa0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
27fb0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
27fc0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
27fd0 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
27fe0 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
27ff0 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
28000 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
28010 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
28020 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
28030 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
28040 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
28050 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
28060 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
28070 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
28080 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28090 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
280a0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
280b0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
280c0 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
280d0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
280e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
280f0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
28100 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
28110 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
28120 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
28130 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
28140 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
28150 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
28160 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
28170 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
28180 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
28190 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
281a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
281b0 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
281c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
281d0 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
281e0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
281f0 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
28200 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
28210 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
28220 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
28230 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
28240 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
28250 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
28260 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
28270 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
28280 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
28290 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
282a0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
282b0 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
282c0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
282d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
282e0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
282f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
28300 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
28310 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
28320 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
28330 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
28340 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
28350 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
28360 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
28370 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
28380 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
28390 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
283a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
283b0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
283c0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
283d0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
283e0 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
283f0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
28400 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
28410 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
28420 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
28430 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
28440 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
28450 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
28460 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
28470 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
28480 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
28490 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
284a0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
284b0 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
284c0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
284d0 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
284e0 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
284f0 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
28500 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
28510 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
28520 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
28530 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
28540 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
28550 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
28560 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
28570 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
28580 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
28590 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
285a0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
285b0 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
285c0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
285d0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
285e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
285f0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
28600 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28610 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
28620 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
28630 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
28640 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
28650 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
28660 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
28670 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
28680 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
28690 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
286a0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
286b0 42 20 69 73 20 74 6f 20 6c 6f 6e 67 20 74 6f 20  B is to long to 
286c0 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
286d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
286e0 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  sult_nomem() int
286f0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
28700 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
28710 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61   error.** indica
28720 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
28730 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
28740 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
28750 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28760 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
28770 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
28780 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
28790 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
287a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
287b0 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
287c0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
287d0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
287e0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
287f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28800 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
28810 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
28820 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
28830 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
28840 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
28850 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
28860 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
28870 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
28880 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
28890 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
288a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
288b0 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
288c0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
288d0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
288e0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
288f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
28900 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
28910 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28920 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
28930 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28940 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
28950 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
28960 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
28970 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
28980 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
28990 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
289a0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
289b0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
289c0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
289d0 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
289e0 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
289f0 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
28a00 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
28a10 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
28a20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
28a30 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
28a40 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
28a50 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
28a60 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
28a70 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
28a80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
28a90 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
28aa0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
28ab0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28ac0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
28ad0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
28ae0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
28af0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
28b00 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
28b10 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
28b20 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
28b30 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
28b40 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
28b50 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
28b60 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
28b70 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
28b80 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
28b90 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
28ba0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
28bb0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
28bc0 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
28bd0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
28be0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
28bf0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
28c00 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
28c10 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
28c20 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
28c30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
28c40 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
28c50 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  ion result..** ^
28c60 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
28c70 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
28c80 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
28c90 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
28ca0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
28cb0 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
28cc0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
28cd0 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
28ce0 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
28cf0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
28d00 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
28d10 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
28d20 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
28d30 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
28d40 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
28d50 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
28d60 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
28d70 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
28d80 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
28d90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28da0 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
28db0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
28dc0 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
28dd0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
28de0 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
28df0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
28e00 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
28e10 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
28e20 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
28e30 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
28e40 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
28e50 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
28e60 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
28e70 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
28e80 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
28e90 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
28ea0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
28eb0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
28ec0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
28ed0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
28ee0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
28ef0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
28f00 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
28f10 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
28f20 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
28f30 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
28f40 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
28f50 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
28f60 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
28f70 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
28f80 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
28f90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
28fa0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
28fb0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
28fc0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
28fd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
28fe0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
28ff0 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
29000 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
29010 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
29020 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
29030 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
29040 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
29050 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
29060 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
29070 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
29080 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
29090 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
290a0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
290b0 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
290c0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
290d0 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
290e0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
290f0 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
29100 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
29110 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
29120 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
29130 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
29140 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
29150 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
29160 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
29170 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29180 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
29190 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
291a0 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
291b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
291c0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
291d0 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
291e0 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
291f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
29200 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
29210 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
29220 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
29230 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
29240 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
29250 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
29260 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
29270 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
29280 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
29290 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
292a0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
292b0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
292c0 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
292d0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
292e0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
292f0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
29300 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
29310 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
29320 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
29330 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
29340 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
29350 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
29360 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
29370 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
29380 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
29390 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
293a0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
293b0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
293c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
293d0 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
293e0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
293f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
29400 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
29410 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
29420 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29430 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
29440 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
29450 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
29460 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
29470 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
29480 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
29490 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
294a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
294b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
294c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
294d0 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
294e0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
294f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
29500 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
29510 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
29520 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
29530 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
29540 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29550 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
29560 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
29570 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
29580 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
29590 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
295a0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
295b0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
295c0 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
295d0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
295e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
295f0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
29600 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
29610 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
29620 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
29630 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
29640 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
29650 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
29660 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
29670 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
29680 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
29690 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
296a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
296b0 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
296c0 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
296d0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
296e0 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
296f0 20 61 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69   add new collati
29700 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20  on sequences to 
29710 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
29720 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
29730 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
29740 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
29750 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
29760 20 74 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69   the new collati
29770 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 73  on sequence is s
29780 70 65 63 69 66 69 65 64 20 61 73 20 61 20 55 54  pecified as a UT
29790 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f  F-8 string.** fo
297a0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
297b0 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64  _collation() and
297c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
297d0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a  collation_v2().*
297e0 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73  * and a UTF-16 s
297f0 74 72 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65  tring for sqlite
29800 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
29810 6f 6e 31 36 28 29 2e 20 5e 49 6e 20 61 6c 6c 20  on16(). ^In all 
29820 63 61 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  cases.** the nam
29830 65 20 69 73 20 70 61 73 73 65 64 20 61 73 20 74  e is passed as t
29840 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
29850 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
29860 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
29870 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e  gument may be on
29880 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
29890 74 73 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  ts [SQLITE_UTF8]
298a0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  ,.** [SQLITE_UTF
298b0 31 36 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16LE], or [SQLIT
298c0 45 5f 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69  E_UTF16BE], indi
298d0 63 61 74 69 6e 67 20 74 68 61 74 20 74 68 65 20  cating that the 
298e0 75 73 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  user-supplied.**
298f0 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73   routine expects
29900 20 74 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f   to be passed po
29910 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
29920 73 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  s encoded using 
29930 55 54 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36  UTF-8,.** UTF-16
29940 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20   little-endian, 
29950 6f 72 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e  or UTF-16 big-en
29960 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
29970 6c 79 2e 20 5e 54 68 65 0a 2a 2a 20 74 68 69 72  ly. ^The.** thir
29980 64 20 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74  d argument might
29990 20 61 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45   also be [SQLITE
299a0 5f 55 54 46 31 36 5d 20 74 6f 20 69 6e 64 69 63  _UTF16] to indic
299b0 61 74 65 20 74 68 61 74 20 74 68 65 20 72 6f 75  ate that the rou
299c0 74 69 6e 65 0a 2a 2a 20 65 78 70 65 63 74 73 20  tine.** expects 
299d0 70 6f 69 6e 74 65 72 73 20 74 6f 20 62 65 20 55  pointers to be U
299e0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 69 6e  TF-16 strings in
299f0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
29a00 20 6f 72 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a   order, or the.*
29a10 2a 20 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62  * argument can b
29a20 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  e [SQLITE_UTF16_
29a30 41 4c 49 47 4e 45 44 5d 20 69 66 20 74 68 65 0a  ALIGNED] if the.
29a40 2a 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65  ** the routine e
29a50 78 70 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20  xpects pointers 
29a60 74 6f 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61  to 16-bit word a
29a70 6c 69 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a  ligned strings.*
29a80 2a 20 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74  * of UTF-16 in t
29a90 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
29aa0 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f  rder..**.** A po
29ab0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 75 73 65  inter to the use
29ac0 72 20 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69  r supplied routi
29ad0 6e 65 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  ne must be passe
29ae0 64 20 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a  d as the fifth.*
29af0 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66  * argument.  ^If
29b00 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69   it is NULL, thi
29b10 73 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  s is the same as
29b20 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
29b30 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65  llation.** seque
29b40 6e 63 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c  nce (so that SQL
29b50 69 74 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20  ite cannot call 
29b60 69 74 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20  it anymore)..** 
29b70 5e 45 61 63 68 20 74 69 6d 65 20 74 68 65 20 61  ^Each time the a
29b80 70 70 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c  pplication suppl
29b90 69 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ied function is 
29ba0 69 6e 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70  invoked, it is p
29bb0 61 73 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20  assed.** as its 
29bc0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
29bd0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
29be0 69 64 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  id* passed as th
29bf0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
29c00 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
29c10 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
29c20 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
29c30 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
29c40 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72  ()..**.** ^The r
29c50 65 6d 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e  emaining argumen
29c60 74 73 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ts to the applic
29c70 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72  ation-supplied r
29c80 6f 75 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73  outine are two s
29c90 74 72 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20  trings,.** each 
29ca0 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 61  represented by a
29cb0 20 28 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20   (length, data) 
29cc0 70 61 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64  pair and encoded
29cd0 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67   in the encoding
29ce0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 70 61 73  .** that was pas
29cf0 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
29d00 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74   argument when t
29d10 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  he collation seq
29d20 75 65 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67  uence was.** reg
29d30 69 73 74 65 72 65 64 2e 20 20 54 68 65 20 61 70  istered.  The ap
29d40 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
29d50 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74  d collation rout
29d60 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ine should.** re
29d70 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a  turn negative, z
29d80 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20  ero or positive 
29d90 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
29da0 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
29db0 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f  ,.** equal to, o
29dc0 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
29dd0 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67  he second string
29de0 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20  . i.e. (STRING1 
29df0 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a  - STRING2)..**.*
29e00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
29e10 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
29e20 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
29e30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
29e40 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78  ollation().** ex
29e50 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61 6b  cept that it tak
29e60 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67 75  es an extra argu
29e70 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
29e80 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a  destructor for.*
29e90 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e  * the collation.
29ea0 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
29eb0 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e  r is called when
29ec0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
29ed0 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61  s.** destroyed a
29ee0 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20 63  nd is passed a c
29ef0 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74  opy of the fourt
29f00 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64  h parameter void
29f10 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20  * pointer.** of 
29f20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  the sqlite3_crea
29f30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
29f40 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
29f50 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 20  s are destroyed 
29f60 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
29f70 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
29f80 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  r calls to the.*
29f90 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  * collation crea
29fa0 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
29fb0 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61  r when the [data
29fc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
29fd0 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73   is closed.** us
29fe0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
29ff0 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  se()]..**.** See
2a000 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
2a010 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2a020 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
2a030 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2a040 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
2a050 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2a060 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
2a070 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2a080 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2a090 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2a0a0 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43  void*,.  int(*xC
2a0b0 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
2a0c0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
2a0d0 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29  t,const void*).)
2a0e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2a0f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2a100 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
2a110 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
2a120 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
2a130 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  tRep, .  void*,.
2a140 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2a150 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2a160 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2a170 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28   void*),.  void(
2a180 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
2a190 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
2a1a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2a1b0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  n16(.  sqlite3*,
2a1c0 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   .  const void *
2a1d0 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65  zName,.  int eTe
2a1e0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
2a1f0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2a200 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2a210 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2a220 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a  t void*).);../*.
2a230 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
2a240 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61  lation Needed Ca
2a250 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
2a260 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74  o avoid having t
2a270 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63  o register all c
2a280 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2a290 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61  es before a data
2a2a0 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75  base.** can be u
2a2b0 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61  sed, a single ca
2a2c0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
2a2d0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
2a2e0 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64  d with the.** [d
2a2f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a300 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c 6c 65 64  on] to be called
2a310 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
2a320 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
2a330 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
2a340 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2a350 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
2a360 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
2a370 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2a380 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2a390 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
2a3a0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
2a3b0 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
2a3c0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
2a3d0 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
2a3e0 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
2a3f0 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
2a400 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2a410 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
2a420 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
2a430 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
2a440 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
2a450 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2a460 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
2a470 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
2a480 20 72 65 70 6c 61 63 65 73 20 61 6e 79 20 65 78   replaces any ex
2a490 69 73 74 69 6e 67 20 63 61 6c 6c 62 61 63 6b 2e  isting callback.
2a4a0 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68  .**.** ^(When th
2a4b0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
2a4c0 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
2a4d0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
2a4e0 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
2a4f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2a500 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2a510 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2a520 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2a530 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2a540 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
2a550 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2a560 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
2a570 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
2a580 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
2a590 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2a5a0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
2a5b0 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20  UTF16BE],.** or 
2a5c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2a5d0 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
2a5e0 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20   most desirable 
2a5f0 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c  form of the coll
2a600 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
2a610 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
2a620 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68  red.  The fourth
2a630 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2a640 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
2a650 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74   required collat
2a660 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a  ion sequence.)^.
2a670 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
2a680 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
2a690 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
2a6a0 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
2a6b0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
2a6c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2a6d0 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
2a6e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2a6f0 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
2a700 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2a710 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
2a720 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2a730 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2a740 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2a750 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
2a760 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
2a770 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
2a780 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e  nst char*).);.in
2a790 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
2a7a0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
2a7b0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
2a7c0 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
2a7d0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
2a7e0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
2a7f0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
2a800 20 53 70 65 63 69 66 79 20 74 68 65 20 6b 65 79   Specify the key
2a810 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 74 65   for an encrypte
2a820 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 68 69  d database.  Thi
2a830 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64  s routine should
2a840 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69   be.** called ri
2a850 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 74 65  ght after sqlite
2a860 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_open()..**.** 
2a870 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
2a880 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
2a890 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
2a8a0 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
2a8b0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
2a8c0 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  te..*/.int sqlit
2a8d0 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  e3_key(.  sqlite
2a8e0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2a8f0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2a900 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
2a910 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
2a920 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
2a930 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65  ey     /* The ke
2a940 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y */.);../*.** C
2a950 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e  hange the key on
2a960 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
2a970 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65  e.  If the curre
2a980 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e  nt database is n
2a990 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c  ot.** encrypted,
2a9a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
2a9b0 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20  ll encrypt it.  
2a9c0 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e  If pNew==0 or nN
2a9d0 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61  ew==0, the.** da
2a9e0 74 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70  tabase is decryp
2a9f0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ted..**.** The c
2aa00 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
2aa10 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
2aa20 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
2aa30 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
2aa40 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
2aa50 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2aa60 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2aa70 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2aa80 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2aa90 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2aaa0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2aab0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2aac0 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
2aad0 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
2aae0 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e  CAPI3REF: Suspen
2aaf0 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
2ab00 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a  A Short Time.**.
2ab10 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ab20 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e  sleep() function
2ab30 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72   causes the curr
2ab40 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75  ent thread to su
2ab50 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a  spend execution.
2ab60 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20  ** for at least 
2ab70 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  a number of mill
2ab80 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69  iseconds specifi
2ab90 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65  ed in its parame
2aba0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ter..**.** ^If t
2abb0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
2abc0 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
2abd0 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
2abe0 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
2abf0 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
2ac00 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
2ac10 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
2ac20 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
2ac30 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
2ac40 6e 64 2e 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  nd. ^The number 
2ac50 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
2ac60 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c  of sleep actuall
2ac70 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66  y.** requested f
2ac80 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e  rom the operatin
2ac90 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75  g system is retu
2aca0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  rned..**.** ^SQL
2acb0 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  ite implements t
2acc0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79  his interface by
2acd0 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c   calling the xSl
2ace0 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20  eep().** method 
2acf0 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
2ad00 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
2ad10 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ect..*/.int sqli
2ad20 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
2ad30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ad40 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
2ad50 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
2ad60 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
2ad70 2a 20 5e 49 66 20 74 68 69 73 20 67 6c 6f 62 61  * ^If this globa
2ad80 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
2ad90 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
2ada0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
2adb0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
2adc0 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
2add0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
2ade0 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
2adf0 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
2ae00 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20   by SQLite when 
2ae10 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e  using a built-in
2ae20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
2ae30 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  VFS].** will be 
2ae40 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
2ae50 69 72 65 63 74 6f 72 79 2e 20 20 5e 49 66 20 74  irectory.  ^If t
2ae60 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
2ae70 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2ae80 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70  r, then SQLite p
2ae90 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68  erforms a search
2aea0 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
2aeb0 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
2aec0 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
2aed0 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
2aee0 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
2aef0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
2af00 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68  iable in more th
2af10 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64  an one.** thread
2af20 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20   at a time.  It 
2af30 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
2af40 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
2af50 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2af60 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
2af70 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
2af80 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73  ng used at the s
2af90 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65  ame time in a se
2afa0 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64  parate.** thread
2afb0 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e  ..** It is inten
2afc0 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
2afd0 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
2afe0 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
2aff0 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
2b000 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
2b010 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
2b020 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
2b030 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
2b040 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68  lled and that th
2b050 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61  is variable rema
2b060 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  in unchanged.** 
2b070 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a  thereafter..**.*
2b080 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f  * ^The [temp_sto
2b090 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
2b0a0 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20  gma] may modify 
2b0b0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e  this variable an
2b0c0 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f  d cause.** it to
2b0d0 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
2b0e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2b0f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e  sqlite3_malloc].
2b100 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a    ^Furthermore,.
2b110 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  ** the [temp_sto
2b120 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
2b130 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75  gma] always assu
2b140 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72  mes that any str
2b150 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73  ing.** that this
2b160 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73   variable points
2b170 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d   to is held in m
2b180 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
2b190 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
2b1a0 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65  _malloc] and the
2b1b0 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65   pragma may atte
2b1c0 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74  mpt to free that
2b1d0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67   memory.** using
2b1e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e   [sqlite3_free].
2b1f0 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68  .** Hence, if th
2b200 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  is variable is m
2b210 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79  odified directly
2b220 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75  , either it shou
2b230 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55  ld be.** made NU
2b240 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f  LL or made to po
2b250 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
2b260 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2b270 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20  ite3_malloc].** 
2b280 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20  or else the use 
2b290 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  of the [temp_sto
2b2a0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
2b2b0 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61  gma] should be a
2b2c0 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  voided..*/.SQLIT
2b2d0 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
2b2e0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
2b2f0 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
2b300 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72  PI3REF: Test For
2b310 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
2b320 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  e.** KEYWORDS: {
2b330 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d  autocommit mode}
2b340 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b350 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
2b360 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  it() interface r
2b370 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
2b380 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68  or.** zero if th
2b390 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65  e given database
2b3a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2b3b0 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f  r is not in auto
2b3c0 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20  commit mode,.** 
2b3d0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e  respectively.  ^
2b3e0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
2b3f0 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  is on by default
2b400 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
2b410 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
2b420 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73  d by a [BEGIN] s
2b430 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75  tatement..** ^Au
2b440 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2b450 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
2b460 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
2b470 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
2b480 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
2b490 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
2b4a0 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
2b4b0 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
2b4c0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
2b4d0 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69  action (errors i
2b4e0 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
2b4f0 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
2b500 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  IOERR],.** [SQLI
2b510 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
2b520 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
2b530 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
2b540 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
2b550 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
2b560 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
2b570 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
2b580 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
2b590 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68  * find out wheth
2b5a0 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  er SQLite automa
2b5b0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
2b5c0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2b5d0 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
2b5e0 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
2b5f0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
2b600 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
2b610 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
2b620 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
2b630 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
2b640 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2b650 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
2b660 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
2b670 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
2b680 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e  n value.** is un
2b690 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
2b6a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
2b6b0 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29  commit(sqlite3*)
2b6c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b6d0 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61  F: Find The Data
2b6e0 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41  base Handle Of A
2b6f0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2b700 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ent.**.** ^The s
2b710 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
2b720 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b730 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ns the [database
2b740 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
2b750 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20  dle.** to which 
2b760 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2b770 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20  ement] belongs. 
2b780 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20   ^The [database 
2b790 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72  connection].** r
2b7a0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2b7b0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20  e3_db_handle is 
2b7c0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
2b7d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
2b7e0 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66  * that was the f
2b7f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
2b800 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2b810 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63  _prepare_v2()] c
2b820 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69  all (or its vari
2b830 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75  ants) that was u
2b840 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65  sed to.** create
2b850 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2b860 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
2b870 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  e..*/.sqlite3 *s
2b880 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
2b890 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2b8a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b8b0 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
2b8c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b8d0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  nt.**.** ^This i
2b8e0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2b8f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2b900 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64  e next [prepared
2b910 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65   statement] afte
2b920 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63  r.** pStmt assoc
2b930 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
2b940 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b950 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70  ion] pDb.  ^If p
2b960 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
2b970 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
2b980 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2b990 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
2b9a0 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
2b9b0 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
2b9c0 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
2b9d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b9e0 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72   pDb.  ^If no pr
2b9f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ba00 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68  .** satisfies th
2ba10 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20  e conditions of 
2ba20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74  this routine, it
2ba30 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
2ba40 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61  *.** The [databa
2ba50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
2ba60 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
2ba70 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2ba80 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29  3_next_stmt(D,S)
2ba90 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20  ] must refer to 
2baa0 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
2bab0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  .** connection a
2bac0 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
2bad0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
2bae0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
2baf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71  sqlite3_stmt *sq
2bb00 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2bb10 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71  sqlite3 *pDb, sq
2bb20 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2bb30 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2bb40 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
2bb50 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
2bb60 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
2bb70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bb80 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2bb90 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
2bba0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
2bbb0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
2bbc0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
2bbd0 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
2bbe0 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f   is [COMMIT | co
2bbf0 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e  mmitted]..** ^An
2bc00 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2bc10 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2bc20 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
2bc30 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
2bc40 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
2bc50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2bc60 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
2bc70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f   ^The sqlite3_ro
2bc80 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e  llback_hook() in
2bc90 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2bca0 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
2bcb0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
2bcc0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2bcd0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2bce0 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c   [ROLLBACK | rol
2bcf0 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41  led back]..** ^A
2bd00 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2bd10 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2bd20 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f  ll to sqlite3_ro
2bd30 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a  llback_hook().**
2bd40 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
2bd50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2bd60 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
2bd70 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72  .** ^The pArg ar
2bd80 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64  gument is passed
2bd90 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
2bda0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66  callback..** ^If
2bdb0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e   the callback on
2bdc0 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66   a commit hook f
2bdd0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
2bde0 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65  non-zero,.** the
2bdf0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20  n the commit is 
2be00 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
2be10 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
2be20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2be30 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  mmit_hook(D,C,P)
2be40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c   and sqlite3_rol
2be50 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50  lback_hook(D,C,P
2be60 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72  ) functions.** r
2be70 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75  eturn the P argu
2be80 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
2be90 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74  evious call of t
2bea0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2beb0 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
2bec0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bed0 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
2bee0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73   for.** the firs
2bef0 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20  t call for each 
2bf00 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a  function on D..*
2bf10 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
2bf20 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
2bf30 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
2bf40 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
2bf50 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
2bf60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2bf70 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
2bf80 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e  he callback.  An
2bf90 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
2bfa0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2bfb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2bfc0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
2bfd0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
2bfe0 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
2bff0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2c000 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
2c010 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f  triggered the co
2c020 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62  mmit.** or rollb
2c030 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20  ack hook in the 
2c040 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20  first place..** 
2c050 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2c060 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2c070 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2c080 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2c090 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2c0a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2c0b0 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2c0c0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2c0d0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2c0e0 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e  *.** ^Registerin
2c0f0 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f  g a NULL functio
2c100 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  n disables the c
2c110 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
2c120 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  When the commit 
2c130 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f  hook callback ro
2c140 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65  utine returns ze
2c150 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d  ro, the [COMMIT]
2c160 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  .** operation is
2c170 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74   allowed to cont
2c180 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20  inue normally.  
2c190 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  ^If the commit h
2c1a0 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e  ook.** returns n
2c1b0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
2c1c0 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f  e [COMMIT] is co
2c1d0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b  nverted into a [
2c1e0 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54  ROLLBACK]..** ^T
2c1f0 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  he rollback hook
2c200 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
2c210 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72   rollback that r
2c220 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f  esults from a co
2c230 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74  mmit.** hook ret
2c240 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c  urning non-zero,
2c250 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c   just as it woul
2c260 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74  d be with any ot
2c270 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  her rollback..**
2c280 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
2c290 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50  poses of this AP
2c2a0 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  I, a transaction
2c2b0 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65   is said to have
2c2c0 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20   been.** rolled 
2c2d0 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69  back if an expli
2c2e0 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73  cit "ROLLBACK" s
2c2f0 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63  tatement is exec
2c300 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65  uted, or.** an e
2c310 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69  rror or constrai
2c320 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70  nt causes an imp
2c330 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74  licit rollback t
2c340 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65  o occur..** ^The
2c350 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
2c360 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
2c370 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
2c380 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  on is.** automat
2c390 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2c3a0 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64  ck because the d
2c3b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c3c0 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
2c3d0 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63   ^The rollback c
2c3e0 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
2c3f0 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
2c400 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 72 6f  saction is.** ro
2c410 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
2c420 65 20 61 20 63 6f 6d 6d 69 74 20 63 61 6c 6c 62  e a commit callb
2c430 61 63 6b 20 72 65 74 75 72 6e 65 64 20 6e 6f 6e  ack returned non
2c440 2d 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  -zero..**.** See
2c450 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
2c460 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2c470 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a  ] interface..*/.
2c480 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c490 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  mmit_hook(sqlite
2c4a0 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
2c4b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69 64 20  ), void*);.void 
2c4c0 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
2c4d0 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
2c4e0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
2c4f0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
2c500 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
2c510 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
2c520 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
2c530 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c540 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
2c550 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
2c560 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
2c570 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
2c580 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2c590 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66  nection] identif
2c5a0 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
2c5b0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
2c5c0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
2c5d0 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
2c5e0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
2c5f0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41  r deleted..** ^A
2c600 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2c610 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2c620 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
2c630 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ion.** for the s
2c640 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
2c650 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
2c660 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  idden..**.** ^Th
2c670 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2c680 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
2c690 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
2c6a0 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a  o invoke when a.
2c6b0 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
2c6c0 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
2c6d0 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  eleted..** ^The 
2c6e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2c6f0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
2c700 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2c710 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
2c720 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  * to sqlite3_upd
2c730 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e  ate_hook()..** ^
2c740 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62  The second callb
2c750 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
2c760 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2c770 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
2c780 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  DELETE],.** or [
2c790 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20  SQLITE_UPDATE], 
2c7a0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
2c7b0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
2c7c0 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
2c7d0 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ack.** to be inv
2c7e0 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68  oked..** ^The th
2c7f0 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
2c800 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
2c810 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
2c820 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
2c830 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64  .** database and
2c840 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
2c850 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
2c860 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65  ted row..** ^The
2c870 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
2c880 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2c890 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
2c8a0 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  row..** ^In the 
2c8b0 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
2c8c0 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b  e, this is the [
2c8d0 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65  rowid] after the
2c8e0 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
2c8f0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ace..**.** ^(The
2c900 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
2c910 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
2c920 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
2c930 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
2c940 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
2c950 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
2c960 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
2c970 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  .)^.**.** ^In th
2c980 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
2c990 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70  entation, the up
2c9a0 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20  date hook.** is 
2c9b0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
2c9c0 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77   duplication row
2c9d0 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65  s are deleted be
2c9e0 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b  cause of an.** [
2c9f0 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e  ON CONFLICT | ON
2ca00 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43   CONFLICT REPLAC
2ca10 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72  E] clause.  ^Nor
2ca20 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68   is the update h
2ca30 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77  ook.** invoked w
2ca40 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c  hen rows are del
2ca50 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  eted using the [
2ca60 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
2ca70 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65  ation]..** The e
2ca80 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65  xceptions define
2ca90 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  d in this paragr
2caa0 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65  aph might change
2cab0 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
2cac0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
2cad0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64  e..**.** The upd
2cae0 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65  ate hook impleme
2caf0 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
2cb00 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
2cb10 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
2cb20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2cb30 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
2cb40 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65  voked the update
2cb50 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69   hook.  Any acti
2cb60 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
2cb70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2cb80 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
2cb90 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
2cba0 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
2cbb0 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
2cbc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2cbd0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
2cbe0 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  red the update h
2cbf0 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ook..** Note tha
2cc00 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
2cc10 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2cc20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
2cc30 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
2cc40 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
2cc50 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
2cc60 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
2cc70 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
2cc80 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  graph..**.** ^Th
2cc90 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
2cca0 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
2ccb0 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73  ction.** returns
2ccc0 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
2ccd0 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
2cce0 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65  s call.** on the
2ccf0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
2cd00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
2cd10 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
2cd20 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20  e first call on 
2cd30 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  D..**.** See als
2cd40 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
2cd50 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e  ommit_hook()] an
2cd60 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d [sqlite3_rollb
2cd70 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69  ack_hook()].** i
2cd80 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 76 6f  nterfaces..*/.vo
2cd90 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70 64 61  id *sqlite3_upda
2cda0 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c 69 74  te_hook(.  sqlit
2cdb0 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29 28  e3*, .  void(*)(
2cdc0 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68 61 72  void *,int ,char
2cdd0 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20 63 6f   const *,char co
2cde0 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  nst *,sqlite3_in
2cdf0 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a 29 3b  t64),.  void*.);
2ce00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ce10 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
2ce20 62 6c 65 20 53 68 61 72 65 64 20 50 61 67 65 72  ble Shared Pager
2ce30 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57 4f 52   Cache.** KEYWOR
2ce40 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61 63 68  DS: {shared cach
2ce50 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e}.**.** ^(This 
2ce60 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20  routine enables 
2ce70 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
2ce80 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65 20 64  sharing of the d
2ce90 61 74 61 62 61 73 65 20 63 61 63 68 65 0a 2a 2a  atabase cache.**
2cea0 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61 74 61   and schema data
2ceb0 20 73 74 72 75 63 74 75 72 65 73 20 62 65 74 77   structures betw
2cec0 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  een [database co
2ced0 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e 6e 65  nnection | conne
2cee0 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20 74 68  ctions].** to th
2cef0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e  e same database.
2cf00 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62   Sharing is enab
2cf10 6c 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d  led if the argum
2cf20 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a 20 61  ent is true.** a
2cf30 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66 20 74  nd disabled if t
2cf40 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 66  he argument is f
2cf50 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43  alse.)^.**.** ^C
2cf60 61 63 68 65 20 73 68 61 72 69 6e 67 20 69 73 20  ache sharing is 
2cf70 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69 73 61  enabled and disa
2cf80 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e 74 69  bled for an enti
2cf90 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a 20 54  re process..** T
2cfa0 68 69 73 20 69 73 20 61 20 63 68 61 6e 67 65 20  his is a change 
2cfb0 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  as of SQLite ver
2cfc0 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e 20 70  sion 3.5.0. In p
2cfd0 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  rior versions of
2cfe0 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68 61 72   SQLite,.** shar
2cff0 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65 64 20  ing was enabled 
2d000 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  or disabled for 
2d010 65 61 63 68 20 74 68 72 65 61 64 20 73 65 70 61  each thread sepa
2d020 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  rately..**.** ^(
2d030 54 68 65 20 63 61 63 68 65 20 73 68 61 72 69 6e  The cache sharin
2d040 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20 74 68  g mode set by th
2d050 69 73 20 69 6e 74 65 72 66 61 63 65 20 65 66 66  is interface eff
2d060 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65 71 75  ects all subsequ
2d070 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
2d080 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
2d090 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
2d0a0 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  v2()], and [sqli
2d0b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 0a 2a  te3_open16()]..*
2d0c0 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74 61 62  * Existing datab
2d0d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2d0e0 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74 68 65  continue use the
2d0f0 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a 2a 2a   sharing mode.**
2d100 20 74 68 61 74 20 77 61 73 20 69 6e 20 65 66 66   that was in eff
2d110 65 63 74 20 61 74 20 74 68 65 20 74 69 6d 65 20  ect at the time 
2d120 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e 65 64  they were opened
2d130 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  .)^.**.** ^(This
2d140 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2d150 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 20   [SQLITE_OK] if 
2d160 73 68 61 72 65 64 20 63 61 63 68 65 20 77 61 73  shared cache was
2d170 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
2d180 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73 73 66  bled.** successf
2d190 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72 6f 72  ully.  An [error
2d1a0 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
2d1b0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 29 5e 0a  ed otherwise.)^.
2d1c0 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20 63 61  **.** ^Shared ca
2d1d0 63 68 65 20 69 73 20 64 69 73 61 62 6c 65 64 20  che is disabled 
2d1e0 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75 74 20  by default. But 
2d1f0 74 68 69 73 20 6d 69 67 68 74 20 63 68 61 6e 67  this might chang
2d200 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 72  e in.** future r
2d210 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
2d220 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  e.  Applications
2d230 20 74 68 61 74 20 63 61 72 65 20 61 62 6f 75 74   that care about
2d240 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65   shared.** cache
2d250 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c 64 20   setting should 
2d260 73 65 74 20 69 74 20 65 78 70 6c 69 63 69 74 6c  set it explicitl
2d270 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41 6c 73  y..**.** See Als
2d280 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68 61 72  o:  [SQLite Shar
2d290 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d 0a 2a  ed-Cache Mode].*
2d2a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
2d2b0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
2d2c0 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e(int);../*.** C
2d2d0 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74  API3REF: Attempt
2d2e0 20 54 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65   To Free Heap Me
2d2f0 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  mory.**.** ^The 
2d300 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2d310 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61  memory() interfa
2d320 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66  ce attempts to f
2d330 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f  ree N bytes.** o
2d340 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79  f heap memory by
2d350 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f   deallocating no
2d360 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f  n-essential memo
2d370 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a  ry allocations.*
2d380 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20 64 61  * held by the da
2d390 74 61 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20  tabase library. 
2d3a0 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f    Memory used to
2d3b0 20 63 61 63 68 65 20 64 61 74 61 62 61 73 65 0a   cache database.
2d3c0 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72  ** pages to impr
2d3d0 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
2d3e0 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
2d3f0 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
2d400 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74  emory..** ^sqlit
2d410 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
2d420 79 28 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  y() returns the 
2d430 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2d440 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a  actually freed,.
2d450 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74 20 62  ** which might b
2d460 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74  e more or less t
2d470 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72  han the amount r
2d480 65 71 75 65 73 74 65 64 2e 0a 2a 2f 0a 69 6e 74  equested..*/.int
2d490 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65   sqlite3_release
2d4a0 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f  _memory(int);../
2d4b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
2d4c0 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e  mpose A Limit On
2d4d0 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a   Heap Size.**.**
2d4e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
2d4f0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 29 20  ft_heap_limit() 
2d500 69 6e 74 65 72 66 61 63 65 20 70 6c 61 63 65 73  interface places
2d510 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 0a   a "soft" limit.
2d520 2a 2a 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74  ** on the amount
2d530 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
2d540 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f  that may be allo
2d550 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  cated by SQLite.
2d560 0a 2a 2a 20 5e 49 66 20 61 6e 20 69 6e 74 65 72  .** ^If an inter
2d570 6e 61 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  nal allocation i
2d580 73 20 72 65 71 75 65 73 74 65 64 20 74 68 61 74  s requested that
2d590 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
2d5a0 65 0a 2a 2a 20 73 6f 66 74 20 68 65 61 70 20 6c  e.** soft heap l
2d5b0 69 6d 69 74 2c 20 5b 73 71 6c 69 74 65 33 5f 72  imit, [sqlite3_r
2d5c0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d  elease_memory()]
2d5d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 65 20   is invoked one 
2d5e0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 69 6d 65 73  or.** more times
2d5f0 20 74 6f 20 66 72 65 65 20 75 70 20 73 6f 6d 65   to free up some
2d600 20 73 70 61 63 65 20 62 65 66 6f 72 65 20 74 68   space before th
2d610 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  e allocation is 
2d620 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 0a 2a 2a  performed..**.**
2d630 20 5e 54 68 65 20 6c 69 6d 69 74 20 69 73 20 63   ^The limit is c
2d640 61 6c 6c 65 64 20 22 73 6f 66 74 22 2c 20 62 65  alled "soft", be
2d650 63 61 75 73 65 20 69 66 20 5b 73 71 6c 69 74 65  cause if [sqlite
2d660 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2d670 28 29 5d 0a 2a 2a 20 63 61 6e 6e 6f 74 20 66 72  ()].** cannot fr
2d680 65 65 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  ee sufficient me
2d690 6d 6f 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20  mory to prevent 
2d6a0 74 68 65 20 6c 69 6d 69 74 20 66 72 6f 6d 20 62  the limit from b
2d6b0 65 69 6e 67 20 65 78 63 65 65 64 65 64 2c 0a 2a  eing exceeded,.*
2d6c0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  * the memory is 
2d6d0 61 6c 6c 6f 63 61 74 65 64 20 61 6e 79 77 61 79  allocated anyway
2d6e0 20 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74   and the current
2d6f0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
2d700 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 6e 65  eds..**.** ^A ne
2d710 67 61 74 69 76 65 20 6f 72 20 7a 65 72 6f 20 76  gative or zero v
2d720 61 6c 75 65 20 66 6f 72 20 4e 20 6d 65 61 6e 73  alue for N means
2d730 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20 6e   that there is n
2d740 6f 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  o soft heap limi
2d750 74 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  t and.** [sqlite
2d760 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
2d770 28 29 5d 20 77 69 6c 6c 20 6f 6e 6c 79 20 62 65  ()] will only be
2d780 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 6d 65 6d   called when mem
2d790 6f 72 79 20 69 73 20 65 78 68 61 75 73 74 65 64  ory is exhausted
2d7a0 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
2d7b0 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  t value for the 
2d7c0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2d7d0 69 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  is zero..**.** ^
2d7e0 28 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  (SQLite makes a 
2d7f0 62 65 73 74 20 65 66 66 6f 72 74 20 74 6f 20 68  best effort to h
2d800 6f 6e 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65  onor the soft he
2d810 61 70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 42 75 74  ap limit..** But
2d820 20 69 66 20 74 68 65 20 73 6f 66 74 20 68 65 61   if the soft hea
2d830 70 20 6c 69 6d 69 74 20 63 61 6e 6e 6f 74 20 62  p limit cannot b
2d840 65 20 68 6f 6e 6f 72 65 64 2c 20 65 78 65 63 75  e honored, execu
2d850 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  tion will.** con
2d860 74 69 6e 75 65 20 77 69 74 68 6f 75 74 20 65 72  tinue without er
2d870 72 6f 72 20 6f 72 20 6e 6f 74 69 66 69 63 61 74  ror or notificat
2d880 69 6f 6e 2e 29 5e 20 20 54 68 69 73 20 69 73 20  ion.)^  This is 
2d890 77 68 79 20 74 68 65 20 6c 69 6d 69 74 20 69 73  why the limit is
2d8a0 0a 2a 2a 20 63 61 6c 6c 65 64 20 61 20 22 73 6f  .** called a "so
2d8b0 66 74 22 20 6c 69 6d 69 74 2e 20 20 49 74 20 69  ft" limit.  It i
2d8c0 73 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e  s advisory only.
2d8d0 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
2d8e0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2d8f0 2e 35 2e 30 2c 20 74 68 69 73 20 72 6f 75 74 69  .5.0, this routi
2d900 6e 65 20 6f 6e 6c 79 20 63 6f 6e 73 74 72 61 69  ne only constrai
2d910 6e 65 64 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ned the memory.*
2d920 2a 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 61  * allocated by a
2d930 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 20 2d   single thread -
2d940 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2d950 20 69 6e 20 77 68 69 63 68 20 74 68 69 73 20 72   in which this r
2d960 6f 75 74 69 6e 65 0a 2a 2a 20 72 75 6e 73 2e 20  outine.** runs. 
2d970 20 42 65 67 69 6e 6e 69 6e 67 20 77 69 74 68 20   Beginning with 
2d980 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2d990 2e 35 2e 30 2c 20 74 68 65 20 73 6f 66 74 20 68  .5.0, the soft h
2d9a0 65 61 70 20 6c 69 6d 69 74 20 69 73 0a 2a 2a 20  eap limit is.** 
2d9b0 61 70 70 6c 69 65 64 20 74 6f 20 61 6c 6c 20 74  applied to all t
2d9c0 68 72 65 61 64 73 2e 20 54 68 65 20 76 61 6c 75  hreads. The valu
2d9d0 65 20 73 70 65 63 69 66 69 65 64 20 66 6f 72 20  e specified for 
2d9e0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
2d9f0 6d 69 74 0a 2a 2a 20 69 73 20 61 6e 20 75 70 70  mit.** is an upp
2da00 65 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 65 20  er bound on the 
2da10 74 6f 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  total memory all
2da20 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 6c 6c 20  ocation for all 
2da30 74 68 72 65 61 64 73 2e 20 49 6e 0a 2a 2a 20 76  threads. In.** v
2da40 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 74 68 65  ersion 3.5.0 the
2da50 72 65 20 69 73 20 6e 6f 20 6d 65 63 68 61 6e 69  re is no mechani
2da60 73 6d 20 66 6f 72 20 6c 69 6d 69 74 69 6e 67 20  sm for limiting 
2da70 74 68 65 20 68 65 61 70 20 75 73 61 67 65 20 66  the heap usage f
2da80 6f 72 0a 2a 2a 20 69 6e 64 69 76 69 64 75 61 6c  or.** individual
2da90 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69   threads..*/.voi
2daa0 64 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  d sqlite3_soft_h
2dab0 65 61 70 5f 6c 69 6d 69 74 28 69 6e 74 29 3b 0a  eap_limit(int);.
2dac0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2dad0 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74   Extract Metadat
2dae0 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e  a About A Column
2daf0 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a   Of A Table.**.*
2db00 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
2db10 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61  returns metadata
2db20 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69   about a specifi
2db30 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70  c column of a sp
2db40 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61  ecific.** databa
2db50 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 69  se table accessi
2db60 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64  ble using the [d
2db70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2db80 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61  on] handle.** pa
2db90 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
2dba0 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  t function argum
2dbb0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
2dbc0 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69  column is identi
2dbd0 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
2dbe0 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f  nd, third and fo
2dbf0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
2dc00 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74  to.** this funct
2dc10 69 6f 6e 2e 20 5e 28 54 68 65 20 73 65 63 6f 6e  ion. ^(The secon
2dc20 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65  d parameter is e
2dc30 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f  ither the name o
2dc40 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
2dc50 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20  * (i.e. "main", 
2dc60 22 74 65 6d 70 22 20 6f 72 20 61 6e 20 61 74 74  "temp" or an att
2dc70 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20  ached database) 
2dc80 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73  containing the s
2dc90 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c  pecified.** tabl
2dca0 65 20 6f 72 20 4e 55 4c 4c 2e 20 49 66 20 69 74  e or NULL. If it
2dcb0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61   is NULL, then a
2dcc0 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ll attached data
2dcd0 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68  bases are search
2dce0 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61  ed.** for the ta
2dcf0 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61  ble using the sa
2dd00 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65  me algorithm use
2dd10 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
2dd20 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72  e engine to.** r
2dd30 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69  esolve unqualifi
2dd40 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e  ed table referen
2dd50 63 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ces.)^.**.** ^Th
2dd60 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
2dd70 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
2dd80 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   this function a
2dd90 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64  re the table and
2dda0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20   column.** name 
2ddb0 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63  of the desired c
2ddc0 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76  olumn, respectiv
2ddd0 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20  ely. Neither of 
2dde0 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73  these parameters
2ddf0 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e  .** may be NULL.
2de00 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61  .**.** ^Metadata
2de10 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
2de20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d  writing to the m
2de30 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20  emory locations 
2de40 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74  passed as the 5t
2de50 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75  h.** and subsequ
2de60 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ent parameters t
2de70 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
2de80 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61   ^Any of these a
2de90 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a  rguments may be.
2dea0 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63  ** NULL, in whic
2deb0 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65  h case the corre
2dec0 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74  sponding element
2ded0 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20   of metadata is 
2dee0 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  omitted..**.** ^
2def0 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  (<blockquote>.**
2df00 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
2df10 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
2df20 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f  Parameter <th> O
2df30 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74  utput<br>Type <t
2df40 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a  h>  Description.
2df50 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35  **.** <tr><td> 5
2df60 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
2df70 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79  ar* <td> Data ty
2df80 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36  pe.** <tr><td> 6
2df90 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
2dfa0 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66  ar* <td> Name of
2dfb0 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69   default collati
2dfc0 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c  on sequence.** <
2dfd0 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e  tr><td> 7th <td>
2dfe0 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
2dff0 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
2e000 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
2e010 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74  constraint.** <t
2e020 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20  r><td> 8th <td> 
2e030 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
2e040 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
2e050 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
2e060 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74  RIMARY KEY.** <t
2e070 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20  r><td> 9th <td> 
2e080 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
2e090 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
2e0a0 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e  is [AUTOINCREMEN
2e0b0 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  T].** </table>.*
2e0c0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
2e0d0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ^.**.** ^The mem
2e0e0 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ory pointed to b
2e0f0 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20  y the character 
2e100 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
2e110 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63  d for the.** dec
2e120 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e  laration type an
2e130 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
2e140 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e  ence is valid on
2e150 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  ly until the nex
2e160 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79  t.** call to any
2e170 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63   SQLite API func
2e180 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tion..**.** ^If 
2e190 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61  the specified ta
2e1a0 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20  ble is actually 
2e1b0 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f  a view, an [erro
2e1c0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
2e1d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
2e1e0 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c  he specified col
2e1f0 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20  umn is "rowid", 
2e200 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64  "oid" or "_rowid
2e210 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e  _" and an.** [IN
2e220 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
2e230 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  Y] column has be
2e240 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
2e250 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
2e260 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
2e270 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f  eters are set fo
2e280 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79  r the explicitly
2e290 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
2e2a0 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 20  . ^(If there is 
2e2b0 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79  no.** explicitly
2e2c0 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47   declared [INTEG
2e2d0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
2e2e0 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65  column, then the
2e2f0 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
2e300 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73  eters are set as
2e310 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
2e320 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
2e330 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
2e340 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
2e350 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
2e360 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
2e370 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
2e380 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
2e390 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
2e3a0 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
2e3b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  >)^.**.** ^(This
2e3c0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f   function may lo
2e3d0 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ad one or more s
2e3e0 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61  chemas from data
2e3f0 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61  base files. If a
2e400 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72  n.** error occur
2e410 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72  s during this pr
2e420 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65  ocess, or if the
2e430 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65   requested table
2e440 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61   or column.** ca
2e450 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61  nnot be found, a
2e460 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2e470 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61  s returned and a
2e480 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
2e490 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b  left.** in the [
2e4a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2e4b0 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72  ion] (to be retr
2e4c0 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69  ieved using sqli
2e4d0 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e  te3_errmsg()).)^
2e4e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49  .**.** ^This API
2e4f0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
2e500 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
2e510 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
2e520 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
2e530 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
2e540 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
2e550 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
2e560 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74   defined..*/.int
2e570 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63   sqlite3_table_c
2e580 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a  olumn_metadata(.
2e590 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2e5a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2e5b0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64   Connection hand
2e5c0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2e5d0 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
2e5e0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2e5f0 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a  name or NULL */.
2e600 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
2e610 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a  ableName,     /*
2e620 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20   Table name */. 
2e630 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f   const char *zCo
2e640 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20  lumnName,    /* 
2e650 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20  Column name */. 
2e660 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a   char const **pz
2e670 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20  DataType,    /* 
2e680 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64  OUTPUT: Declared
2e690 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20   data type */.  
2e6a0 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43  char const **pzC
2e6b0 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f  ollSeq,     /* O
2e6c0 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e  UTPUT: Collation
2e6d0 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a   sequence name *
2e6e0 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c  /.  int *pNotNul
2e6f0 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
2e700 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
2e710 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73  if NOT NULL cons
2e720 74 72 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f  traint exists */
2e730 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79  .  int *pPrimary
2e740 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Key,           /
2e750 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69  * OUTPUT: True i
2e760 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66  f column part of
2e770 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41   PK */.  int *pA
2e780 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20  utoinc          
2e790 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2e7a0 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69  True if column i
2e7b0 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74  s auto-increment
2e7c0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2e7d0 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20  PI3REF: Load An 
2e7e0 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  Extension.**.** 
2e7f0 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  ^This interface 
2e800 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20  loads an SQLite 
2e810 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
2e820 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64  y from the named
2e830 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   file..**.** ^Th
2e840 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  e sqlite3_load_e
2e850 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
2e860 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
2e870 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69   load an.** SQLi
2e880 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62  te extension lib
2e890 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69  rary contained i
2e8a0 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65  n the file zFile
2e8b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74  ..**.** ^The ent
2e8c0 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f  ry point is zPro
2e8d0 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79  c..** ^zProc may
2e8e0 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20   be 0, in which 
2e8f0 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66  case the name of
2e900 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74   the entry point
2e910 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74 6f 20  .** defaults to 
2e920 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69  "sqlite3_extensi
2e930 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68  on_init"..** ^Th
2e940 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  e sqlite3_load_e
2e950 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72  xtension() inter
2e960 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
2e970 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
2e980 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49  uccess and [SQLI
2e990 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d  TE_ERROR] if som
2e9a0 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ething goes wron
2e9b0 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  g..** ^If an err
2e9c0 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a  or occurs and pz
2e9d0 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c  ErrMsg is not 0,
2e9e0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71   then the.** [sq
2e9f0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
2ea00 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63  sion()] interfac
2ea10 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20  e shall attempt 
2ea20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72  to.** fill *pzEr
2ea30 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f 72 20  rMsg with error 
2ea40 6d 65 73 73 61 67 65 20 74 65 78 74 20 73 74 6f  message text sto
2ea50 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a  red in memory.**
2ea60 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2ea70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2ea80 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66  ]. The calling f
2ea90 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  unction.** shoul
2eaa0 64 20 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f  d free this memo
2eab0 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ry by calling [s
2eac0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2ead0 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e  **.** ^Extension
2eae0 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65   loading must be
2eaf0 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a   enabled using.*
2eb00 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  * [sqlite3_enabl
2eb10 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
2eb20 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  ()] prior to cal
2eb30 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a  ling this API,.*
2eb40 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65  * otherwise an e
2eb50 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74  rror will be ret
2eb60 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  urned..**.** See
2eb70 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f   also the [load_
2eb80 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20  extension() SQL 
2eb90 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e  function]..*/.in
2eba0 74 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65  t sqlite3_load_e
2ebb0 78 74 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69  xtension(.  sqli
2ebc0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2ebd0 20 20 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78    /* Load the ex
2ebe0 74 65 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69  tension into thi
2ebf0 73 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  s database conne
2ec00 63 74 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74  ction */.  const
2ec10 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20   char *zFile,   
2ec20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
2ec30 73 68 61 72 65 64 20 6c 69 62 72 61 72 79 20 63  shared library c
2ec40 6f 6e 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73  ontaining extens
2ec50 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
2ec60 68 61 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f  har *zProc,    /
2ec70 2a 20 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20  * Entry point.  
2ec80 44 65 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69  Derived from zFi
2ec90 6c 65 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61  le if 0 */.  cha
2eca0 72 20 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20  r **pzErrMsg    
2ecb0 20 20 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20     /* Put error 
2ecc0 6d 65 73 73 61 67 65 20 68 65 72 65 20 69 66 20  message here if 
2ecd0 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  not 0 */.);../*.
2ece0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
2ecf0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
2ed00 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
2ed10 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f  .**.** ^So as no
2ed20 74 20 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69  t to open securi
2ed30 74 79 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65  ty holes in olde
2ed40 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  r applications t
2ed50 68 61 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65  hat are.** unpre
2ed60 70 61 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69  pared to deal wi
2ed70 74 68 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  th extension loa
2ed80 64 69 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d  ding, and as a m
2ed90 65 61 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e  eans of disablin
2eda0 67 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c  g.** extension l
2edb0 6f 61 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61  oading while eva
2edc0 6c 75 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74  luating user-ent
2edd0 65 72 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f  ered SQL, the fo
2ede0 6c 6c 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69  llowing API.** i
2edf0 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75  s provided to tu
2ee00 72 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  rn the [sqlite3_
2ee10 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2ee20 5d 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61  ] mechanism on a
2ee30 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45  nd off..**.** ^E
2ee40 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
2ee50 20 69 73 20 6f 66 66 20 62 79 20 64 65 66 61 75   is off by defau
2ee60 6c 74 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23  lt. See ticket #
2ee70 31 38 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74  1863..** ^Call t
2ee80 68 65 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  he sqlite3_enabl
2ee90 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
2eea0 28 29 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  () routine with 
2eeb0 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74  onoff==1.** to t
2eec0 75 72 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f  urn extension lo
2eed0 61 64 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c  ading on and cal
2eee0 6c 20 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d  l it with onoff=
2eef0 3d 30 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74  =0 to turn.** it
2ef00 20 62 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e   back off again.
2ef10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2ef20 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
2ef30 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64  nsion(sqlite3 *d
2ef40 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  b, int onoff);..
2ef50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2ef60 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f  Automatically Lo
2ef70 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 73  ad An Extensions
2ef80 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49  .**.** ^This API
2ef90 20 63 61 6e 20 62 65 20 69 6e 76 6f 6b 65 64 20   can be invoked 
2efa0 61 74 20 70 72 6f 67 72 61 6d 20 73 74 61 72 74  at program start
2efb0 75 70 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72  up in order to r
2efc0 65 67 69 73 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  egister.** one o
2efd0 72 20 6d 6f 72 65 20 73 74 61 74 69 63 61 6c 6c  r more staticall
2efe0 79 20 6c 69 6e 6b 65 64 20 65 78 74 65 6e 73 69  y linked extensi
2eff0 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  ons that will be
2f000 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 74 6f   available.** to
2f010 20 61 6c 6c 20 6e 65 77 20 5b 64 61 74 61 62 61   all new [databa
2f020 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e  se connections].
2f030 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2f040 75 74 69 6e 65 20 73 74 6f 72 65 73 20 61 20 70  utine stores a p
2f050 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 65 78  ointer to the ex
2f060 74 65 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f  tension entry po
2f070 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  int.** in an arr
2f080 61 79 20 74 68 61 74 20 69 73 20 6f 62 74 61 69  ay that is obtai
2f090 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2f0a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
2f0b0 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20  at memory.** is 
2f0c0 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 5b  deallocated by [
2f0d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75  sqlite3_reset_au
2f0e0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e  to_extension()].
2f0f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  )^.**.** ^This f
2f100 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
2f110 73 20 61 6e 20 65 78 74 65 6e 73 69 6f 6e 20 65  s an extension e
2f120 6e 74 72 79 20 70 6f 69 6e 74 20 74 68 61 74 20  ntry point that 
2f130 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  is.** automatica
2f140 6c 6c 79 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  lly invoked when
2f150 65 76 65 72 20 61 20 6e 65 77 20 5b 64 61 74 61  ever a new [data
2f160 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2f170 0a 2a 2a 20 69 73 20 6f 70 65 6e 65 64 20 75 73  .** is opened us
2f180 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  ing [sqlite3_ope
2f190 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2f1a0 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72 20  pen16()],.** or 
2f1b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2f1c0 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70 6c 69 63 61  ()]..** ^Duplica
2f1d0 74 65 20 65 78 74 65 6e 73 69 6f 6e 73 20 61 72  te extensions ar
2f1e0 65 20 64 65 74 65 63 74 65 64 20 73 6f 20 63 61  e detected so ca
2f1f0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
2f200 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 74  ne.** multiple t
2f210 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
2f220 6d 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20  me extension is 
2f230 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a 20 5e 41 75  harmless..** ^Au
2f240 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f  tomatic extensio
2f250 6e 73 20 61 70 70 6c 79 20 61 63 72 6f 73 73 20  ns apply across 
2f260 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a  all threads..*/.
2f270 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f  int sqlite3_auto
2f280 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20  _extension(void 
2f290 28 2a 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76  (*xEntryPoint)(v
2f2a0 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid));../*.** CA
2f2b0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 75  PI3REF: Reset Au
2f2c0 74 6f 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f  tomatic Extensio
2f2d0 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20  n Loading.**.** 
2f2e0 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  ^(This function 
2f2f0 64 69 73 61 62 6c 65 73 20 61 6c 6c 20 70 72 65  disables all pre
2f300 76 69 6f 75 73 6c 79 20 72 65 67 69 73 74 65 72  viously register
2f310 65 64 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  ed automatic.** 
2f320 65 78 74 65 6e 73 69 6f 6e 73 2e 20 49 74 20 75  extensions. It u
2f330 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
2f340 20 6f 66 20 61 6c 6c 20 70 72 69 6f 72 0a 2a 2a   of all prior.**
2f350 20 5b 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65   [sqlite3_auto_e
2f360 78 74 65 6e 73 69 6f 6e 28 29 5d 20 63 61 6c 6c  xtension()] call
2f370 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  s.)^.**.** ^This
2f380 20 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c   function disabl
2f390 65 73 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74  es automatic ext
2f3a0 65 6e 73 69 6f 6e 73 20 69 6e 20 61 6c 6c 20 74  ensions in all t
2f3b0 68 72 65 61 64 73 2e 0a 2a 2f 0a 76 6f 69 64 20  hreads..*/.void 
2f3c0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75  sqlite3_reset_au
2f3d0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69  to_extension(voi
2f3e0 64 29 3b 0a 0a 2f 2a 0a 2a 2a 2a 2a 2a 2a 20 45  d);../*.****** E
2f3f0 58 50 45 52 49 4d 45 4e 54 41 4c 20 2d 20 73 75  XPERIMENTAL - su
2f400 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
2f410 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 20 2a  without notice *
2f420 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a  *************.**
2f430 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
2f440 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
2f450 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
2f460 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f   is currently co
2f470 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62  nsidered.** to b
2f480 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20  e experimental. 
2f490 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d   The interface m
2f4a0 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69  ight change in i
2f4b0 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73  ncompatible ways
2f4c0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20  ..** If this is 
2f4d0 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f  a problem for yo
2f4e0 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68  u, do not use th
2f4f0 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74  e interface at t
2f500 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  his time..**.** 
2f510 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c  When the virtual
2f520 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
2f530 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20   stabilizes, we 
2f540 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65  will declare the
2f550 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69  .** interface fi
2f560 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20  xed, support it 
2f570 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e  indefinitely, an
2f580 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f  d remove this co
2f590 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  mment..*/../*.**
2f5a0 20 53 74 72 75 63 74 75 72 65 73 20 75 73 65 64   Structures used
2f5b0 20 62 79 20 74 68 65 20 76 69 72 74 75 61 6c 20   by the virtual 
2f5c0 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a  table interface.
2f5d0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2f5e0 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73  t sqlite3_vtab s
2f5f0 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70  qlite3_vtab;.typ
2f600 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
2f610 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73  te3_index_info s
2f620 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
2f630 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  o;.typedef struc
2f640 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  t sqlite3_vtab_c
2f650 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74  ursor sqlite3_vt
2f660 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64  ab_cursor;.typed
2f670 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2f680 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33  3_module sqlite3
2f690 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20  _module;../*.** 
2f6a0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
2f6b0 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a  l Table Object.*
2f6c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
2f6d0 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74  te3_module {virt
2f6e0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
2f6f0 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41  }.** EXPERIMENTA
2f700 4c 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72  L.**.** This str
2f710 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65  ucture, sometime
2f720 73 20 63 61 6c 6c 65 64 20 61 20 61 20 22 76 69  s called a a "vi
2f730 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
2f740 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73  le", .** defines
2f750 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2f760 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61  ion of a [virtua
2f770 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20  l tables].  .** 
2f780 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  This structure c
2f790 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f  onsists mostly o
2f7a0 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  f methods for th
2f7b0 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20  e module..**.** 
2f7c0 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ^A virtual table
2f7d0 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74   module is creat
2f7e0 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e  ed by filling in
2f7f0 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a   a persistent.**
2f800 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
2f810 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20  s structure and 
2f820 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65  passing a pointe
2f830 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e  r to that instan
2f840 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ce.** to [sqlite
2f850 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
2f860 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
2f870 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
2f880 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69  )]..** ^The regi
2f890 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73  stration remains
2f8a0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20   valid until it 
2f8b0 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  is replaced by a
2f8c0 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f   different.** mo
2f8d0 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68  dule or until th
2f8e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2f8f0 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20  ection] closes. 
2f900 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   The content.** 
2f910 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
2f920 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67  e must not chang
2f930 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72 65  e while it is re
2f940 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a  gistered with.**
2f950 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
2f960 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72  nnection..*/.str
2f970 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  uct sqlite3_modu
2f980 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  le {.  int iVers
2f990 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72  ion;.  int (*xCr
2f9a0 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20  eate)(sqlite3*, 
2f9b0 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
2f9c0 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
2f9d0 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
2f9e0 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
2f9f0 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
2fa00 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
2fa10 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
2fa20 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71  t (*xConnect)(sq
2fa30 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
2fa40 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
2fa50 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
2fa60 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
2fa70 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
2fa80 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
2fa90 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
2faa0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73  *);.  int (*xBes
2fab0 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f  tIndex)(sqlite3_
2fac0 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
2fad0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a  ite3_index_info*
2fae0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63  );.  int (*xDisc
2faf0 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f  onnect)(sqlite3_
2fb00 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
2fb10 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28  int (*xDestroy)(
2fb20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
2fb30 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f  Tab);.  int (*xO
2fb40 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  pen)(sqlite3_vta
2fb50 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
2fb60 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a  3_vtab_cursor **
2fb70 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74  ppCursor);.  int
2fb80 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
2fb90 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
2fba0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65  ;.  int (*xFilte
2fbb0 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  r)(sqlite3_vtab_
2fbc0 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78  cursor*, int idx
2fbd0 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Num, const char 
2fbe0 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20  *idxStr,.       
2fbf0 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
2fc00 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  c, sqlite3_value
2fc10 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20   **argv);.  int 
2fc20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33  (*xNext)(sqlite3
2fc30 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
2fc40 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71    int (*xEof)(sq
2fc50 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
2fc60 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  r*);.  int (*xCo
2fc70 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  lumn)(sqlite3_vt
2fc80 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
2fc90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2fca0 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77  t);.  int (*xRow
2fcb0 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  id)(sqlite3_vtab
2fcc0 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
2fcd0 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29  3_int64 *pRowid)
2fce0 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74  ;.  int (*xUpdat
2fcf0 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
2fd00 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
2fd10 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65  value **, sqlite
2fd20 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e  3_int64 *);.  in
2fd30 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69  t (*xBegin)(sqli
2fd40 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
2fd50 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
2fd60 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2fd70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2fd80 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f  Commit)(sqlite3_
2fd90 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
2fda0 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29  int (*xRollback)
2fdb0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
2fdc0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
2fdd0 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71  FindFunction)(sq
2fde0 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
2fdf0 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e  b, int nArg, con
2fe00 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a  st char *zName,.
2fe10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fe20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70         void (**p
2fe30 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2fe40 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2fe50 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2fe60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fe70 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72       void **ppAr
2fe80 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e  g);.  int (*xRen
2fe90 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ame)(sqlite3_vta
2fea0 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20  b *pVtab, const 
2feb0 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a  char *zNew);.};.
2fec0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fed0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
2fee0 6e 64 65 78 69 6e 67 20 49 6e 66 6f 72 6d 61 74  ndexing Informat
2fef0 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ion.** KEYWORDS:
2ff00 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
2ff10 6e 66 6f 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  nfo.** EXPERIMEN
2ff20 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  TAL.**.** The sq
2ff30 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
2ff40 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20 69   structure and i
2ff50 74 73 20 73 75 62 73 74 72 75 63 74 75 72 65 73  ts substructures
2ff60 20 69 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 70   is used to.** p
2ff70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ass information 
2ff80 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65  into and receive
2ff90 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20   the reply from 
2ffa0 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d  the [xBestIndex]
2ffb0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20  .** method of a 
2ffc0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
2ffd0 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65  odule].  The fie
2ffe0 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75  lds under **Inpu
2fff0 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20  ts** are the.** 
30000 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49  inputs to xBestI
30010 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61  ndex and are rea
30020 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e  d-only.  xBestIn
30030 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a  dex inserts its.
30040 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
30050 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20  the **Outputs** 
30060 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  fields..**.** ^(
30070 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
30080 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20  ] array records 
30090 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
300a0 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20  straints of the 
300b0 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  form:.**.** <pre
300c0 3e 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c  >column OP expr<
300d0 2f 70 72 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72  /pre>.**.** wher
300e0 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c  e OP is =, &lt;,
300f0 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72   &lt;=, &gt;, or
30100 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 54 68 65 20   &gt;=.)^  ^The 
30110 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61  particular opera
30120 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64  tor is.** stored
30130 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b   in aConstraint[
30140 5d 2e 6f 70 2e 20 20 5e 54 68 65 20 69 6e 64 65  ].op.  ^The inde
30150 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
30160 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20  is stored in.** 
30170 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
30180 6f 6c 75 6d 6e 2e 20 20 5e 28 61 43 6f 6e 73 74  olumn.  ^(aConst
30190 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69  raint[].usable i
301a0 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a  s TRUE if the.**
301b0 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67   expr on the rig
301c0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e  ht-hand side can
301d0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61   be evaluated (a
301e0 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73  nd thus the cons
301f0 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61  traint.** is usa
30200 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69  ble) and false i
30210 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a  f it cannot.)^.*
30220 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69  *.** ^The optimi
30230 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  zer automaticall
30240 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20  y inverts terms 
30250 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70  of the form "exp
30260 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20  r OP column".** 
30270 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20  and makes other 
30280 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20  simplifications 
30290 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  to the WHERE cla
302a0 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70  use in an attemp
302b0 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d  t to.** get as m
302c0 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65  any WHERE clause
302d0 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20   terms into the 
302e0 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65  form shown above
302f0 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a   as possible..**
30300 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e   ^The aConstrain
30310 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72  t[] array only r
30320 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61  eports WHERE cla
30330 75 73 65 20 74 65 72 6d 73 20 69 6e 20 74 68 65  use terms in the
30340 20 63 6f 72 72 65 63 74 0a 2a 2a 20 66 6f 72 6d   correct.** form
30350 20 74 68 61 74 20 72 65 66 65 72 20 74 6f 20 74   that refer to t
30360 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 76 69  he particular vi
30370 72 74 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e  rtual table bein
30380 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a  g queried..**.**
30390 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62   ^Information ab
303a0 6f 75 74 20 74 68 65 20 4f 52 44 45 52 20 42 59  out the ORDER BY
303b0 20 63 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65   clause is store
303c0 64 20 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e  d in aOrderBy[].
303d0 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72 6d 20 6f  .** ^Each term o
303e0 66 20 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72  f aOrderBy recor
303f0 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ds a column of t
30400 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
30410 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78  se..**.** The [x
30420 42 65 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f  BestIndex] metho
30430 64 20 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e  d must fill aCon
30440 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77  straintUsage[] w
30450 69 74 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ith information.
30460 2a 2a 20 61 62 6f 75 74 20 77 68 61 74 20 70 61  ** about what pa
30470 72 61 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73  rameters to pass
30480 20 74 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e 49   to xFilter.  ^I
30490 66 20 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68  f argvIndex>0 th
304a0 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d  en.** the right-
304b0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65  hand side of the
304c0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61   corresponding a
304d0 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20  Constraint[] is 
304e0 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64  evaluated.** and
304f0 20 62 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67   becomes the arg
30500 76 49 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20  vIndex-th entry 
30510 69 6e 20 61 72 67 76 2e 20 20 5e 28 49 66 20 61  in argv.  ^(If a
30520 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b  ConstraintUsage[
30530 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75  ].omit.** is tru
30540 65 2c 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73  e, then the cons
30550 74 72 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65  traint is assume
30560 64 20 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61  d to be fully ha
30570 6e 64 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  ndled by the.** 
30580 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e  virtual table an
30590 64 20 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64  d is not checked
305a0 20 61 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65   again by SQLite
305b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69  .)^.**.** ^The i
305c0 64 78 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72  dxNum and idxPtr
305d0 20 76 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f   values are reco
305e0 72 64 65 64 20 61 6e 64 20 70 61 73 73 65 64 20  rded and passed 
305f0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69  into the.** [xFi
30600 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a  lter] method..**
30610 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28   ^[sqlite3_free(
30620 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 66 72  )] is used to fr
30630 65 65 20 69 64 78 50 74 72 20 69 66 20 61 6e 64  ee idxPtr if and
30640 20 6f 6e 6c 79 20 69 66 66 0a 2a 2a 20 6e 65 65   only iff.** nee
30650 64 54 6f 46 72 65 65 49 64 78 50 74 72 20 69 73  dToFreeIdxPtr is
30660 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   true..**.** ^Th
30670 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65  e orderByConsume
30680 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 75 74  d means that out
30690 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65  put from [xFilte
306a0 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20  r]/[xNext] will 
306b0 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20  occur in.** the 
306c0 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20 74 6f  correct order to
306d0 20 73 61 74 69 73 66 79 20 74 68 65 20 4f 52 44   satisfy the ORD
306e0 45 52 20 42 59 20 63 6c 61 75 73 65 20 73 6f 20  ER BY clause so 
306f0 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61 74 65  that no separate
30700 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74 65 70  .** sorting step
30710 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
30720 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d 61 74  .** ^The estimat
30730 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69 73 20  edCost value is 
30740 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 74  an estimate of t
30750 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67  he cost of doing
30760 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c   the.** particul
30770 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75  ar lookup.  A fu
30780 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74 61 62  ll scan of a tab
30790 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72 69 65  le with N entrie
307a0 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  s should have.**
307b0 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41   a cost of N.  A
307c0 20 62 69 6e 61 72 79 20 73 65 61 72 63 68 20 6f   binary search o
307d0 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e 20 65  f a table of N e
307e0 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61  ntries should ha
307f0 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20  ve a.** cost of 
30800 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f  approximately lo
30810 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  g(N)..*/.struct 
30820 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
30830 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73  fo {.  /* Inputs
30840 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74   */.  int nConst
30850 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20  raint;          
30860 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e   /* Number of en
30870 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73 74 72  tries in aConstr
30880 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75 63 74  aint */.  struct
30890 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
308a0 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20 20 20  onstraint {.    
308b0 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
308c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
308d0 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e  lumn on left-han
308e0 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73 74 72  d side of constr
308f0 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73  aint */.     uns
30900 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b 20 20  igned char op;  
30910 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72         /* Constr
30920 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f  aint operator */
30930 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  .     unsigned c
30940 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20 20 20  har usable;     
30950 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69 73 20  /* True if this 
30960 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 75 73  constraint is us
30970 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74  able */.     int
30980 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20 20 20   iTermOffset;   
30990 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64 20 69         /* Used i
309a0 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73  nternally - xBes
309b0 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20 69 67  tIndex should ig
309c0 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f  nore */.  } *aCo
309d0 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
309e0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66       /* Table of
309f0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
30a00 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69  nstraints */.  i
30a10 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20 20 20  nt nOrderBy;    
30a20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
30a30 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
30a40 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
30a50 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63 74 20  use */.  struct 
30a60 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72  sqlite3_index_or
30a70 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69 6e 74  derby {.     int
30a80 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
30a90 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
30aa0 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20   number */.     
30ab0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 64 65  unsigned char de
30ac0 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54 72 75  sc;       /* Tru
30ad0 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46 61 6c  e for DESC.  Fal
30ae0 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20  se for ASC. */. 
30af0 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20 20 20   } *aOrderBy;   
30b00 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54              /* T
30b10 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75  he ORDER BY clau
30b20 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75  se */.  /* Outpu
30b30 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73  ts */.  struct s
30b40 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e  qlite3_index_con
30b50 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a  straint_usage {.
30b60 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e 64 65      int argvInde
30b70 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  x;           /* 
30b80 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e  if >0, constrain
30b90 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 72 67  t is part of arg
30ba0 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a  v to xFilter */.
30bb0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
30bc0 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20  r omit;      /* 
30bd0 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20 74 65  Do not code a te
30be0 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f 6e 73  st for this cons
30bf0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61  traint */.  } *a
30c00 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 3b  ConstraintUsage;
30c10 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20  .  int idxNum;  
30c20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
30c30 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74 6f 20   Number used to 
30c40 69 64 65 6e 74 69 66 79 20 74 68 65 20 69 6e 64  identify the ind
30c50 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64  ex */.  char *id
30c60 78 53 74 72 3b 20 20 20 20 20 20 20 20 20 20 20  xStr;           
30c70 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f     /* String, po
30c80 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65 64 20  ssibly obtained 
30c90 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
30ca0 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65  loc */.  int nee
30cb0 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b 20 20  dToFreeIdxStr;  
30cc0 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64 78 53      /* Free idxS
30cd0 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  tr using sqlite3
30ce0 5f 66 72 65 65 28 29 20 69 66 20 74 72 75 65 20  _free() if true 
30cf0 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72 42 79  */.  int orderBy
30d00 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20 20 20  Consumed;       
30d10 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74 70 75  /* True if outpu
30d20 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f 72 64  t is already ord
30d30 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65  ered */.  double
30d40 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74 3b 20   estimatedCost; 
30d50 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61 74 65       /* Estimate
30d60 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e 67 20  d cost of using 
30d70 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b  this index */.};
30d80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30d90 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
30da0 5f 45 51 20 20 20 20 32 0a 23 64 65 66 69 6e 65  _EQ    2.#define
30db0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
30dc0 4e 53 54 52 41 49 4e 54 5f 47 54 20 20 20 20 34  NSTRAINT_GT    4
30dd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
30de0 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
30df0 5f 4c 45 20 20 20 20 38 0a 23 64 65 66 69 6e 65  _LE    8.#define
30e00 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
30e10 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20 20 20 31  NSTRAINT_LT    1
30e20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
30e30 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
30e40 54 5f 47 45 20 20 20 20 33 32 0a 23 64 65 66 69  T_GE    32.#defi
30e50 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f  ne SQLITE_INDEX_
30e60 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41 54 43 48  CONSTRAINT_MATCH
30e70 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   64../*.** CAPI3
30e80 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
30e90 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6d  Virtual Table Im
30ea0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
30eb0 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a  EXPERIMENTAL.**.
30ec0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
30ed0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 72  es are used to r
30ee0 65 67 69 73 74 65 72 20 61 20 6e 65 77 20 5b 76  egister a new [v
30ef0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
30f00 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d  ule] name..** ^M
30f10 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d 75 73 74  odule names must
30f20 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 62   be registered b
30f30 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61 74 69 6e  efore.** creatin
30f40 67 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61 6c  g a new [virtual
30f50 20 74 61 62 6c 65 5d 20 75 73 69 6e 67 20 74 68   table] using th
30f60 65 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 62 65 66  e module, or bef
30f70 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a 2a 20 70  ore using a.** p
30f80 72 65 65 78 69 73 74 69 6e 67 20 5b 76 69 72 74  reexisting [virt
30f90 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f 72 20 74  ual table] for t
30fa0 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a  he module..**.**
30fb0 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20 6e 61 6d   ^The module nam
30fc0 65 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  e is registered 
30fd0 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  on the [database
30fe0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
30ff0 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
31000 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
31010 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  .  ^The name of 
31020 74 68 65 20 6d 6f 64 75 6c 65 20 69 73 20 67 69  the module is gi
31030 76 65 6e 20 62 79 20 74 68 65 20 0a 2a 2a 20 73  ven by the .** s
31040 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
31050 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72    ^The third par
31060 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
31070 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d  ter to.** the im
31080 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
31090 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
310a0 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 20 5e 54  le module].   ^T
310b0 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20 70 61 72  he fourth.** par
310c0 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
310d0 69 74 72 61 72 79 20 63 6c 69 65 6e 74 20 64 61  itrary client da
310e0 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  ta pointer that 
310f0 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  is passed throug
31100 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 5b 78  h.** into the [x
31110 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f  Create] and [xCo
31120 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f  nnect] methods o
31130 66 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  f the virtual ta
31140 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68  ble module.** wh
31150 65 6e 20 61 20 6e 65 77 20 76 69 72 74 75 61 6c  en a new virtual
31160 20 74 61 62 6c 65 20 69 73 20 62 65 20 62 65 69   table is be bei
31170 6e 67 20 63 72 65 61 74 65 64 20 6f 72 20 72 65  ng created or re
31180 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a  initialized..**.
31190 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
311a0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
311b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 68 61 73  () interface has
311c0 20 61 20 66 69 66 74 68 20 70 61 72 61 6d 65 74   a fifth paramet
311d0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
311e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 65   pointer to a de
311f0 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
31200 20 70 43 6c 69 65 6e 74 44 61 74 61 2e 20 20 5e   pClientData.  ^
31210 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 69  SQLite will.** i
31220 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75  nvoke the destru
31230 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 28 69  ctor function (i
31240 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
31250 29 20 77 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  ) when SQLite.**
31260 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 73   no longer needs
31270 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61   the pClientData
31280 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
31290 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
312a0 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72  odule().** inter
312b0 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65  face is equivale
312c0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  nt to sqlite3_cr
312d0 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
312e0 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20   with a NULL.** 
312f0 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 53  destructor..*/.S
31300 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
31310 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  AL int sqlite3_c
31320 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20  reate_module(.  
31330 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
31340 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
31350 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
31360 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
31370 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
31380 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
31390 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
313a0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
313b0 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
313c0 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a  _module *p,   /*
313d0 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
313e0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
313f0 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20  d *pClientData  
31400 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
31410 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
31420 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29  te/xConnect */.)
31430 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
31440 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65  ENTAL int sqlite
31450 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
31460 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
31470 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
31480 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
31490 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
314a0 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
314b0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
314c0 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
314d0 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
314e0 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
314f0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
31500 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  ,   /* Methods f
31510 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
31520 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74  .  void *pClient
31530 44 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a  Data,         /*
31540 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
31550 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
31560 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65  t */.  void(*xDe
31570 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20  stroy)(void*)   
31580 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74    /* Module dest
31590 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20  ructor function 
315a0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
315b0 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
315c0 61 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62  able Instance Ob
315d0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
315e0 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a  : sqlite3_vtab.*
315f0 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
31600 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74  *.** Every [virt
31610 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
31620 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ] implementation
31630 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73   uses a subclass
31640 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  .** of this obje
31650 63 74 20 74 6f 20 64 65 73 63 72 69 62 65 20 61  ct to describe a
31660 20 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74   particular inst
31670 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ance.** of the [
31680 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20  virtual table]. 
31690 20 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77   Each subclass w
316a0 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72  ill.** be tailor
316b0 65 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  ed to the specif
316c0 69 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20  ic needs of the 
316d0 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  module implement
316e0 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75  ation..** The pu
316f0 72 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75  rpose of this su
31700 70 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64  perclass is to d
31710 65 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69  efine certain fi
31720 65 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  elds that are.**
31730 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d   common to all m
31740 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
31750 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69  tions..**.** ^Vi
31760 72 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74  rtual tables met
31770 68 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20  hods can set an 
31780 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79  error message by
31790 20 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20   assigning a.** 
317a0 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
317b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
317c0 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72  rintf()] to zErr
317d0 4d 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64  Msg.  The method
317e0 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20   should.** take 
317f0 63 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72  care that any pr
31800 69 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72  ior string is fr
31810 65 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f  eed by a call to
31820 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
31830 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73  ].** prior to as
31840 73 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74  signing a new st
31850 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e  ring to zErrMsg.
31860 20 20 5e 41 66 74 65 72 20 74 68 65 20 65 72 72    ^After the err
31870 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73  or message.** is
31880 20 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f   delivered up to
31890 20 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c   the client appl
318a0 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72  ication, the str
318b0 69 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ing will be auto
318c0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65  matically.** fre
318d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72  ed by sqlite3_fr
318e0 65 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72  ee() and the zEr
318f0 72 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20  rMsg field will 
31900 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74  be zeroed..*/.st
31910 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
31920 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69  b {.  const sqli
31930 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64  te3_module *pMod
31940 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64  ule;  /* The mod
31950 75 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72  ule for this vir
31960 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20  tual table */.  
31970 69 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20  int nRef;       
31980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31990 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45  /* NO LONGER USE
319a0 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72  D */.  char *zEr
319b0 72 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20  rMsg;           
319c0 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
319d0 6d 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c  message from sql
319e0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a  ite3_mprintf() *
319f0 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74  /.  /* Virtual t
31a00 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
31a10 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61  ions will typica
31a20 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e  lly add addition
31a30 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a  al fields */.};.
31a40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31a50 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43   Virtual Table C
31a60 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20  ursor Object.** 
31a70 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
31a80 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76  3_vtab_cursor {v
31a90 69 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72  irtual table cur
31aa0 73 6f 72 7d 0a 2a 2a 20 45 58 50 45 52 49 4d 45  sor}.** EXPERIME
31ab0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  NTAL.**.** Every
31ac0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
31ad0 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e  module] implemen
31ae0 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
31af0 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
31b00 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63   following struc
31b10 74 75 72 65 20 74 6f 20 64 65 73 63 72 69 62 65  ture to describe
31b20 20 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f   cursors that po
31b30 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  int into the.** 
31b40 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
31b50 61 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20  and are used.** 
31b60 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20  to loop through 
31b70 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
31b80 65 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20  e.  Cursors are 
31b90 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
31ba0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f  e.** [sqlite3_mo
31bb0 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70  dule.xOpen | xOp
31bc0 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  en] method of th
31bd0 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65  e module and are
31be0 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79   destroyed.** by
31bf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f   the [sqlite3_mo
31c00 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43  dule.xClose | xC
31c10 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43  lose] method.  C
31c20 75 72 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a  ursors are used.
31c30 2a 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74  ** by the [xFilt
31c40 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78  er], [xNext], [x
31c50 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c  Eof], [xColumn],
31c60 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65   and [xRowid] me
31c70 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20  thods.** of the 
31c80 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f  module.  Each mo
31c90 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
31ca0 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a  ion will define.
31cb0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
31cc0 66 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63  f a cursor struc
31cd0 74 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73  ture to suit its
31ce0 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a   own needs..**.*
31cf0 2a 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73  * This superclas
31d00 73 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65  s exists in orde
31d10 72 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c  r to define fiel
31d20 64 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72  ds of the cursor
31d30 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d   that.** are com
31d40 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65  mon to all imple
31d50 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73  mentations..*/.s
31d60 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
31d70 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71  ab_cursor {.  sq
31d80 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
31d90 62 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75  b;      /* Virtu
31da0 61 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73  al table of this
31db0 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20   cursor */.  /* 
31dc0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
31dd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
31de0 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
31df0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
31e00 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ds */.};../*.** 
31e10 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
31e20 65 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20  e The Schema Of 
31e30 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a  A Virtual Table.
31e40 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
31e50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65  **.** ^The [xCre
31e60 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65  ate] and [xConne
31e70 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61  ct] methods of a
31e80 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
31e90 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20  le module] call 
31ea0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a  this interface.*
31eb0 2a 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65  * to declare the
31ec0 20 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d   format (the nam
31ed0 65 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73  es and datatypes
31ee0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29   of the columns)
31ef0 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75   of.** the virtu
31f00 61 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69  al tables they i
31f10 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c  mplement..*/.SQL
31f20 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
31f30 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63   int sqlite3_dec
31f40 6c 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65  lare_vtab(sqlite
31f50 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  3*, const char *
31f60 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  zSQL);../*.** CA
31f70 50 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64  PI3REF: Overload
31f80 20 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20   A Function For 
31f90 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a  A Virtual Table.
31fa0 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  ** EXPERIMENTAL.
31fb0 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20  **.** ^(Virtual 
31fc0 74 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69  tables can provi
31fd0 64 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69  de alternative i
31fe0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
31ff0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75  f functions.** u
32000 73 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46  sing the [xFindF
32010 75 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20  unction] method 
32020 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
32030 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
32040 0a 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76  .** But global v
32050 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65  ersions of those
32060 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75   functions.** mu
32070 73 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65  st exist in orde
32080 72 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64  r to be overload
32090 65 64 2e 29 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ed.).**.** ^(Thi
320a0 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65  s API makes sure
320b0 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f   a global versio
320c0 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20  n of a function 
320d0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
320e0 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75  r.** name and nu
320f0 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65  mber of paramete
32100 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e  rs exists.  If n
32110 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20  o such function 
32120 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65  exists.** before
32130 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c   this API is cal
32140 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74  led, a new funct
32150 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29  ion is created.)
32160 5e 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ^  ^The implemen
32170 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
32180 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c   new function al
32190 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65  ways causes an e
321a0 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74  xception to be t
321b0 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68  hrown.  So.** th
321c0 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  e new function i
321d0 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61  s not good for a
321e0 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c  nything by itsel
321f0 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20  f.  Its only.** 
32200 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65  purpose is to be
32210 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66   a placeholder f
32220 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e  unction that can
32230 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a   be overloaded.*
32240 2a 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20  * by a [virtual 
32250 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  table]..*/.SQLIT
32260 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
32270 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c  nt sqlite3_overl
32280 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c  oad_function(sql
32290 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61  ite3*, const cha
322a0 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e  r *zFuncName, in
322b0 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t nArg);../*.** 
322c0 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
322d0 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
322e0 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66  le mechanism def
322f0 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b  ined above (back
32300 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d   up.** to a comm
32310 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73  ent remarkably s
32320 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f  imilar to this o
32330 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ne) is currently
32340 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74   considered.** t
32350 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61  o be experimenta
32360 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  l.  The interfac
32370 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  e might change i
32380 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  n incompatible w
32390 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  ays..** If this 
323a0 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72  is a problem for
323b0 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65   you, do not use
323c0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61   the interface a
323d0 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a  t this time..**.
323e0 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74  ** When the virt
323f0 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
32400 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20  ism stabilizes, 
32410 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
32420 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
32430 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
32440 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
32450 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
32460 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 2a   comment..**.***
32470 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  *** EXPERIMENTAL
32480 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68   - subject to ch
32490 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e 6f 74  ange without not
324a0 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ice ************
324b0 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  **.*/../*.** CAP
324c0 49 33 52 45 46 3a 20 41 20 48 61 6e 64 6c 65 20  I3REF: A Handle 
324d0 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a  To An Open BLOB.
324e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 42 4c  ** KEYWORDS: {BL
324f0 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42  OB handle} {BLOB
32500 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20   handles}.**.** 
32510 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
32520 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
32530 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 42 4c  sents an open BL
32540 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a 2a 20 5b  OB on which.** [
32550 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
32560 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
32570 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e 20 62 65  BLOB I/O] can be
32580 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e   performed..** ^
32590 4f 62 6a 65 63 74 73 20 6f 66 20 74 68 69 73 20  Objects of this 
325a0 74 79 70 65 20 61 72 65 20 63 72 65 61 74 65 64  type are created
325b0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
325c0 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64  b_open()].** and
325d0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
325e0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
325f0 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  e()]..** ^The [s
32600 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
32610 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
32620 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 69  _blob_write()] i
32630 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 63 61 6e  nterfaces.** can
32640 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 61 64   be used to read
32650 20 6f 72 20 77 72 69 74 65 20 73 6d 61 6c 6c 20   or write small 
32660 73 75 62 73 65 63 74 69 6f 6e 73 20 6f 66 20 74  subsections of t
32670 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65  he BLOB..** ^The
32680 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
32690 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
326a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 69  e returns the si
326b0 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 69  ze of the BLOB i
326c0 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74 79 70 65  n bytes..*/.type
326d0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
326e0 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74 65 33 5f  e3_blob sqlite3_
326f0 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  blob;../*.** CAP
32700 49 33 52 45 46 3a 20 4f 70 65 6e 20 41 20 42 4c  I3REF: Open A BL
32710 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d 65 6e 74  OB For Increment
32720 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54  al I/O.**.** ^(T
32730 68 69 73 20 69 6e 74 65 72 66 61 63 65 73 20 6f  his interfaces o
32740 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20 68 61 6e  pens a [BLOB han
32750 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d 20 74 6f  dle | handle] to
32760 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63 61 74 65   the BLOB locate
32770 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69 52 6f 77  d.** in row iRow
32780 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e  , column zColumn
32790 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c 65 20 69  , table zTable i
327a0 6e 20 64 61 74 61 62 61 73 65 20 7a 44 62 3b 0a  n database zDb;.
327b0 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** in other word
327c0 73 2c 20 74 68 65 20 73 61 6d 65 20 42 4c 4f 42  s, the same BLOB
327d0 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 73   that would be s
327e0 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a  elected by:.**.*
327f0 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 53  * <pre>.**     S
32800 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e 20 46 52  ELECT zColumn FR
32810 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65 20 57 48  OM zDb.zTable WH
32820 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d 20 69 52  ERE [rowid] = iR
32830 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a  ow;.** </pre>)^.
32840 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6c  **.** ^If the fl
32850 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  ags parameter is
32860 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
32870 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e  the BLOB is open
32880 65 64 20 66 6f 72 20 72 65 61 64 0a 2a 2a 20 61  ed for read.** a
32890 6e 64 20 77 72 69 74 65 20 61 63 63 65 73 73 2e  nd write access.
328a0 20 5e 49 66 20 69 74 20 69 73 20 7a 65 72 6f 2c   ^If it is zero,
328b0 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f 70 65   the BLOB is ope
328c0 6e 65 64 20 66 6f 72 20 72 65 61 64 20 61 63 63  ned for read acc
328d0 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 6e  ess..** ^It is n
328e0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f  ot possible to o
328f0 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61  pen a column tha
32900 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 6e 20  t is part of an 
32910 69 6e 64 65 78 20 6f 72 20 70 72 69 6d 61 72 79  index or primary
32920 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20 77 72 69   .** key for wri
32930 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f 72 65 69  ting. ^If [forei
32940 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
32950 74 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 2c  ts] are enabled,
32960 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f 74 20 70   it is .** not p
32970 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20  ossible to open 
32980 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  a column that is
32990 20 70 61 72 74 20 6f 66 20 61 20 5b 63 68 69 6c   part of a [chil
329a0 64 20 6b 65 79 5d 20 66 6f 72 20 77 72 69 74 69  d key] for writi
329b0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  ng..**.** ^Note 
329c0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
329d0 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74 20 74 68  e name is not th
329e0 65 20 66 69 6c 65 6e 61 6d 65 20 74 68 61 74 20  e filename that 
329f0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
32a00 64 61 74 61 62 61 73 65 20 62 75 74 20 72 61 74  database but rat
32a10 68 65 72 20 74 68 65 20 73 79 6d 62 6f 6c 69 63  her the symbolic
32a20 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
32a30 61 62 61 73 65 20 74 68 61 74 0a 2a 2a 20 61 70  abase that.** ap
32a40 70 65 61 72 73 20 61 66 74 65 72 20 74 68 65 20  pears after the 
32a50 41 53 20 6b 65 79 77 6f 72 64 20 77 68 65 6e 20  AS keyword when 
32a60 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
32a70 63 6f 6e 6e 65 63 74 65 64 20 75 73 69 6e 67 20  connected using 
32a80 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f  [ATTACH]..** ^Fo
32a90 72 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  r the main datab
32aa0 61 73 65 20 66 69 6c 65 2c 20 74 68 65 20 64 61  ase file, the da
32ab0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22  tabase name is "
32ac0 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54  main"..** ^For T
32ad0 45 4d 50 20 74 61 62 6c 65 73 2c 20 74 68 65 20  EMP tables, the 
32ae0 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
32af0 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e   "temp"..**.** ^
32b00 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 5b 53 51  (On success, [SQ
32b10 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
32b20 72 6e 65 64 20 61 6e 64 20 74 68 65 20 6e 65 77  rned and the new
32b30 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69   [BLOB handle] i
32b40 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 74 6f 20  s written.** to 
32b50 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65 72 77 69  *ppBlob. Otherwi
32b60 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
32b70 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
32b80 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73 20 73 65  nd *ppBlob is se
32b90 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20 6e 75 6c  t.** to be a nul
32ba0 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20  l pointer.)^.** 
32bb0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73  ^This function s
32bc0 65 74 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  ets the [databas
32bd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 65 72  e connection] er
32be0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
32bf0 73 61 67 65 0a 2a 2a 20 61 63 63 65 73 73 69 62  sage.** accessib
32c00 6c 65 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  le via [sqlite3_
32c10 65 72 72 63 6f 64 65 28 29 5d 20 61 6e 64 20 5b  errcode()] and [
32c20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
32c30 5d 20 61 6e 64 20 72 65 6c 61 74 65 64 0a 2a 2a  ] and related.**
32c40 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74   functions. ^Not
32c50 65 20 74 68 61 74 20 74 68 65 20 2a 70 70 42 6c  e that the *ppBl
32c60 6f 62 20 76 61 72 69 61 62 6c 65 20 69 73 20 61  ob variable is a
32c70 6c 77 61 79 73 20 69 6e 69 74 69 61 6c 69 7a 65  lways initialize
32c80 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79 20 74 68  d in a.** way th
32c90 61 74 20 6d 61 6b 65 73 20 69 74 20 73 61 66 65  at makes it safe
32ca0 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69   to invoke [sqli
32cb0 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
32cc0 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20  ] on *ppBlob.** 
32cd0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
32ce0 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  e success or fai
32cf0 6c 75 72 65 20 6f 66 20 74 68 69 73 20 72 6f 75  lure of this rou
32d00 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  tine..**.** ^(If
32d10 20 74 68 65 20 72 6f 77 20 74 68 61 74 20 61 20   the row that a 
32d20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70 6f 69 6e  BLOB handle poin
32d30 74 73 20 74 6f 20 69 73 20 6d 6f 64 69 66 69 65  ts to is modifie
32d40 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55 50 44 41  d by an.** [UPDA
32d50 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d 2c 20 6f  TE], [DELETE], o
32d60 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  r by [ON CONFLIC
32d70 54 5d 20 73 69 64 65 2d 65 66 66 65 63 74 73 0a  T] side-effects.
32d80 2a 2a 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42  ** then the BLOB
32d90 20 68 61 6e 64 6c 65 20 69 73 20 6d 61 72 6b 65   handle is marke
32da0 64 20 61 73 20 22 65 78 70 69 72 65 64 22 2e 0a  d as "expired"..
32db0 2a 2a 20 54 68 69 73 20 69 73 20 74 72 75 65 20  ** This is true 
32dc0 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66  if any column of
32dd0 20 74 68 65 20 72 6f 77 20 69 73 20 63 68 61 6e   the row is chan
32de0 67 65 64 2c 20 65 76 65 6e 20 61 20 63 6f 6c 75  ged, even a colu
32df0 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  mn.** other than
32e00 20 74 68 65 20 6f 6e 65 20 74 68 65 20 42 4c 4f   the one the BLO
32e10 42 20 68 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e  B handle is open
32e20 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73   on.)^.** ^Calls
32e30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
32e40 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73  b_read()] and [s
32e50 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74  qlite3_blob_writ
32e60 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61 20 65 78  e()] for.** a ex
32e70 70 69 72 65 64 20 42 4c 4f 42 20 68 61 6e 64 6c  pired BLOB handl
32e80 65 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 72  e fail with an r
32e90 65 74 75 72 6e 20 63 6f 64 65 20 6f 66 20 5b 53  eturn code of [S
32ea0 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a  QLITE_ABORT]..**
32eb0 20 5e 28 43 68 61 6e 67 65 73 20 77 72 69 74 74   ^(Changes writt
32ec0 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f 42 20 70  en into a BLOB p
32ed0 72 69 6f 72 20 74 6f 20 74 68 65 20 42 4c 4f 42  rior to the BLOB
32ee0 20 65 78 70 69 72 69 6e 67 20 61 72 65 20 6e 6f   expiring are no
32ef0 74 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 20 62 79  t.** rollback by
32f00 20 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20   the expiration 
32f10 6f 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75  of the BLOB.  Su
32f20 63 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ch changes will 
32f30 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f  eventually.** co
32f40 6d 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e  mmit if the tran
32f50 73 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65  saction continue
32f60 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  s to completion.
32f70 29 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68  )^.**.** ^Use th
32f80 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
32f90 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
32fa0 63 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ce to determine 
32fb0 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74  the size of.** t
32fc0 68 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20  he opened blob. 
32fd0 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20   ^The size of a 
32fe0 62 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20  blob may not be 
32ff0 63 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a  changed by this.
33000 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55  ** interface.  U
33010 73 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20  se the [UPDATE] 
33020 53 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63  SQL command to c
33030 68 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f  hange the size o
33040 66 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a  f a.** blob..**.
33050 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
33060 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
33070 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
33080 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
33090 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
330a0 61 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e  and the built-in
330b0 20 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20   [zeroblob] SQL 
330c0 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20  function can be 
330d0 75 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64  used, if desired
330e0 2c 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61  ,.** to create a
330f0 6e 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69  n empty, zero-fi
33100 6c 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69  lled blob in whi
33110 63 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72  ch to read or wr
33120 69 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69  ite using.** thi
33130 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  s interface..**.
33140 2a 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65  ** To avoid a re
33150 73 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65  source leak, eve
33160 72 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61  ry open [BLOB ha
33170 6e 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65  ndle] should eve
33180 6e 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65  ntually.** be re
33190 6c 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c  leased by a call
331a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
331b0 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69  b_close()]..*/.i
331c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
331d0 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a  open(.  sqlite3*
331e0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
331f0 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  zDb,.  const cha
33200 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e  r *zTable,.  con
33210 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
33220 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  ,.  sqlite3_int6
33230 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c  4 iRow,.  int fl
33240 61 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62  ags,.  sqlite3_b
33250 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a  lob **ppBlob.);.
33260 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33270 20 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61   Close A BLOB Ha
33280 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73  ndle.**.** ^Clos
33290 65 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  es an open [BLOB
332a0 20 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20   handle]..**.** 
332b0 5e 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20  ^Closing a BLOB 
332c0 73 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20  shall cause the 
332d0 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
332e0 69 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a  ion to commit.**
332f0 20 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f   if there are no
33300 20 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f   other BLOBs, no
33310 20 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65   pending prepare
33320 64 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e  d statements, an
33330 64 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  d the.** databas
33340 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
33350 69 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  in [autocommit m
33360 6f 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79  ode]..** ^If any
33370 20 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64   writes were mad
33380 65 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74  e to the BLOB, t
33390 68 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c  hey might be hel
333a0 64 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e  d in cache.** un
333b0 74 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70  til the close op
333c0 65 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20  eration if they 
333d0 77 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20  will fit..**.** 
333e0 5e 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c  ^(Closing the BL
333f0 4f 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20  OB often forces 
33400 74 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  the changes.** o
33410 75 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73  ut to disk and s
33420 6f 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72  o if any I/O err
33430 6f 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20  ors occur, they 
33440 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75  will likely occu
33450 72 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65  r.** at the time
33460 20 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69   when the BLOB i
33470 73 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65  s closed.  Any e
33480 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
33490 20 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69   during.** closi
334a0 6e 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20  ng are reported 
334b0 61 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65  as a non-zero re
334c0 74 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a  turn value.)^.**
334d0 0a 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69  .** ^(The BLOB i
334e0 73 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69  s closed uncondi
334f0 74 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20  tionally.  Even 
33500 69 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  if this routine 
33510 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72  returns.** an er
33520 72 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c  ror code, the BL
33530 4f 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73  OB is still clos
33540 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  ed.)^.**.** ^Cal
33550 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e  ling this routin
33560 65 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f  e with a null po
33570 69 6e 74 65 72 20 28 73 75 63 68 20 61 73 20 77  inter (such as w
33580 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
33590 0a 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20  .** by a failed 
335a0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
335b0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69  _blob_open()]) i
335c0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
335d0 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  op..*/.int sqlit
335e0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71  e3_blob_close(sq
335f0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
33600 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33610 52 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20  Return The Size 
33620 4f 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a  Of An Open BLOB.
33630 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74  **.** ^Returns t
33640 68 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73  he size in bytes
33650 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63   of the BLOB acc
33660 65 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20  essible via the 
33670 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
33680 20 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61   opened [BLOB ha
33690 6e 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c  ndle] in its onl
336a0 79 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  y argument.  ^Th
336b0 65 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c  e.** incremental
336c0 20 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e   blob I/O routin
336d0 65 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64  es can only read
336e0 20 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20   or overwriting 
336f0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62  existing.** blob
33700 20 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63   content; they c
33710 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  annot change the
33720 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e   size of a blob.
33730 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
33740 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f  ine only works o
33750 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  n a [BLOB handle
33760 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e  ] which has been
33770 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61   created.** by a
33780 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
33790 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
337a0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
337b0 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f  and which has no
337c0 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64  t.** been closed
337d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   by [sqlite3_blo
337e0 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73  b_close()].  Pas
337f0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70  sing any other p
33800 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20  ointer in.** to 
33810 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73  this routine res
33820 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65  ults in undefine
33830 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
33840 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
33850 69 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ior..*/.int sqli
33860 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73  te3_blob_bytes(s
33870 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a  qlite3_blob *);.
33880 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33890 20 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20   Read Data From 
338a0 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
338b0 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ally.**.** ^(Thi
338c0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
338d0 65 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20  ed to read data 
338e0 66 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  from an open [BL
338f0 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20  OB handle] into 
33900 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70  a.** caller-supp
33910 6c 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62  lied buffer. N b
33920 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65  ytes of data are
33930 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66   copied into buf
33940 66 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68  fer Z.** from th
33950 65 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61  e open BLOB, sta
33960 72 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20  rting at offset 
33970 69 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a  iOffset.)^.**.**
33980 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66   ^If offset iOff
33990 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
339a0 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
339b0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
339c0 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
339d0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
339e0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
339f0 72 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20  read.  ^If N or 
33a00 69 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65  iOffset is.** le
33a10 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53  ss than zero, [S
33a20 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
33a30 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
33a40 64 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a  data is read..**
33a50 20 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68   ^The size of th
33a60 65 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63  e blob (and henc
33a70 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61  e the maximum va
33a80 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74  lue of N+iOffset
33a90 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  ).** can be dete
33aa0 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  rmined using the
33ab0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
33ac0 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
33ad0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74  e..**.** ^An att
33ae0 65 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f  empt to read fro
33af0 6d 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c  m an expired [BL
33b00 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73  OB handle] fails
33b10 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f   with an.** erro
33b20 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
33b30 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20  E_ABORT]..**.** 
33b40 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71  ^(On success, sq
33b50 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
33b60 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  ) returns SQLITE
33b70 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73  _OK..** Otherwis
33b80 65 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  e, an [error cod
33b90 65 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64  e] or an [extend
33ba0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  ed error code] i
33bb0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
33bc0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
33bd0 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61   only works on a
33be0 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77   [BLOB handle] w
33bf0 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72  hich has been cr
33c00 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72  eated.** by a pr
33c10 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
33c20 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
33c30 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64  blob_open()] and
33c40 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a   which has not.*
33c50 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79  * been closed by
33c60 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
33c70 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e  lose()].  Passin
33c80 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e  g any other poin
33c90 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69  ter in.** to thi
33ca0 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74  s routine result
33cb0 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  s in undefined a
33cc0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
33cd0 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
33ce0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
33cf0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  : [sqlite3_blob_
33d00 77 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  write()]..*/.int
33d10 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65   sqlite3_blob_re
33d20 61 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ad(sqlite3_blob 
33d30 2a 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20  *, void *Z, int 
33d40 4e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b  N, int iOffset);
33d50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33d60 3a 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74  : Write Data Int
33d70 6f 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65  o A BLOB Increme
33d80 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntally.**.** ^Th
33d90 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  is function is u
33da0 73 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74  sed to write dat
33db0 61 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b  a into an open [
33dc0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f  BLOB handle] fro
33dd0 6d 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75  m a.** caller-su
33de0 70 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e  pplied buffer. ^
33df0 4e 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20  N bytes of data 
33e00 61 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20  are copied from 
33e10 74 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  the buffer Z.** 
33e20 69 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c  into the open BL
33e30 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
33e40 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a  offset iOffset..
33e50 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42  **.** ^If the [B
33e60 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73  LOB handle] pass
33e70 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
33e80 61 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74  argument was not
33e90 20 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77   opened for.** w
33ea0 72 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67  riting (the flag
33eb0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  s parameter to [
33ec0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
33ed0 6e 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a  n()] was zero),.
33ee0 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
33ef0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
33f00 5f 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a  _READONLY]..**.*
33f10 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
33f20 20 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79   may only modify
33f30 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66   the contents of
33f40 20 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73   the BLOB; it is
33f50 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
33f60 20 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65   to increase the
33f70 20 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20   size of a BLOB 
33f80 75 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a  using this API..
33f90 2a 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f  ** ^If offset iO
33fa0 66 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68  ffset is less th
33fb0 61 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20  an N bytes from 
33fc0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42  the end of the B
33fd0 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  LOB,.** [SQLITE_
33fe0 45 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e  ERROR] is return
33ff0 65 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69  ed and no data i
34000 73 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 20  s written.  ^If 
34010 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61  N is.** less tha
34020 6e 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45  n zero [SQLITE_E
34030 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
34040 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
34050 20 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65   written..** The
34060 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
34070 42 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65  B (and hence the
34080 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f   maximum value o
34090 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20  f N+iOffset).** 
340a0 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
340b0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c  d using the [sql
340c0 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
340d0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
340e0 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20  .** ^An attempt 
340f0 74 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65  to write to an e
34100 78 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e  xpired [BLOB han
34110 64 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20  dle] fails with 
34120 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  an.** error code
34130 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52   of [SQLITE_ABOR
34140 54 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 6f 20  T].  ^Writes to 
34150 74 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63  the BLOB that oc
34160 63 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65  curred.** before
34170 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   the [BLOB handl
34180 65 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 6e  e] expired are n
34190 6f 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ot rolled back b
341a0 79 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74  y the.** expirat
341b0 69 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c  ion of the handl
341c0 65 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  e, though of cou
341d0 72 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65  rse those change
341e0 73 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20  s might.** have 
341f0 62 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e  been overwritten
34200 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
34210 74 20 74 68 61 74 20 65 78 70 69 72 65 64 20 74  t that expired t
34220 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a  he BLOB handle.*
34230 2a 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e  * or by other in
34240 64 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d  dependent statem
34250 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e  ents..**.** ^(On
34260 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65   success, sqlite
34270 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 72  3_blob_write() r
34280 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
34290 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20  ..** Otherwise, 
342a0 61 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  an  [error code]
342b0 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
342c0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
342d0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
342e0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
342f0 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
34300 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
34310 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
34320 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
34330 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
34340 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
34350 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
34360 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
34370 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
34380 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
34390 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
343a0 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
343b0 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
343c0 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
343d0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
343e0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
343f0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
34400 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
34410 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
34420 61 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ad()]..*/.int sq
34430 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
34440 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
34450 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20   const void *z, 
34460 69 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73  int n, int iOffs
34470 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  et);../*.** CAPI
34480 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69  3REF: Virtual Fi
34490 6c 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74  le System Object
344a0 73 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61  s.**.** A virtua
344b0 6c 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46  l filesystem (VF
344c0 53 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65  S) is an [sqlite
344d0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a  3_vfs] object.**
344e0 20 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65   that SQLite use
344f0 73 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a  s to interact.**
34500 20 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c   with the underl
34510 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
34520 79 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c  ystem.  Most SQL
34530 69 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20  ite builds come 
34540 77 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  with a.** single
34550 20 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61   default VFS tha
34560 74 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65  t is appropriate
34570 20 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f   for the host co
34580 6d 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56  mputer..** New V
34590 46 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69  FSes can be regi
345a0 73 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74  stered and exist
345b0 69 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65  ing VFSes can be
345c0 20 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a   unregistered..*
345d0 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
345e0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
345f0 72 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  rovided..**.** ^
34600 54 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  The sqlite3_vfs_
34610 66 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65  find() interface
34620 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
34630 65 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65  er to a VFS give
34640 6e 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  n its name..** ^
34650 4e 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73  Names are case s
34660 65 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61  ensitive..** ^Na
34670 6d 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  mes are zero-ter
34680 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
34690 72 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  rings..** ^If th
346a0 65 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c  ere is no match,
346b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
346c0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
346d0 5e 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20  ^If zVfsName is 
346e0 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65  NULL then the de
346f0 66 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 74  fault VFS is ret
34700 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65  urned..**.** ^Ne
34710 77 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69  w VFSes are regi
34720 73 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69  stered with sqli
34730 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
34740 28 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77  ()..** ^Each new
34750 20 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65   VFS becomes the
34760 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20   default VFS if 
34770 74 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61  the makeDflt fla
34780 67 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  g is set..** ^Th
34790 65 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62  e same VFS can b
347a0 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
347b0 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
347c0 6f 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e  out injury..** ^
347d0 54 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74  To make an exist
347e0 69 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65  ing VFS into the
347f0 20 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65   default VFS, re
34800 67 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a  gister it again.
34810 2a 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65  ** with the make
34820 44 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20  Dflt flag set.  
34830 49 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74  If two different
34840 20 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a   VFSes with the.
34850 2a 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  ** same name are
34860 20 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65   registered, the
34870 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
34880 65 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a  efined.  If a.**
34890 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72   VFS is register
348a0 65 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74  ed with a name t
348b0 68 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61  hat is NULL or a
348c0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a  n empty string,.
348d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
348e0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
348f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69  d..**.** ^Unregi
34900 73 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20  ster a VFS with 
34910 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f  the sqlite3_vfs_
34920 75 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74  unregister() int
34930 65 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20  erface..** ^(If 
34940 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
34950 69 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c  is unregistered,
34960 20 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20   another VFS is 
34970 63 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65  chosen as.** the
34980 20 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63   default.  The c
34990 68 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65  hoice for the ne
349a0 77 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61  w VFS is arbitra
349b0 72 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33  ry.)^.*/.sqlite3
349c0 5f 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66  _vfs *sqlite3_vf
349d0 73 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61  s_find(const cha
349e0 72 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e  r *zVfsName);.in
349f0 74 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  t sqlite3_vfs_re
34a00 67 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76  gister(sqlite3_v
34a10 66 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c  fs*, int makeDfl
34a20 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
34a30 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73  vfs_unregister(s
34a40 71 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f  qlite3_vfs*);../
34a50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
34a60 75 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  utexes.**.** The
34a70 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
34a80 73 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  s these routines
34a90 20 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73   for thread.** s
34aa0 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20  ynchronization. 
34ab0 54 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20  Though they are 
34ac0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74  intended for int
34ad0 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20  ernal.** use by 
34ae0 53 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61  SQLite, code tha
34af0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
34b00 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72  SQLite is.** per
34b10 6d 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e  mitted to use an
34b20 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
34b30 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  nes..**.** The S
34b40 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64  QLite source cod
34b50 65 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69  e contains multi
34b60 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
34b70 6f 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  ons.** of these 
34b80 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20  mutex routines. 
34b90 20 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   An appropriate 
34ba0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
34bb0 2a 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75  * is selected au
34bc0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63  tomatically at c
34bd0 6f 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28  ompile-time.  ^(
34be0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a  The following.**
34bf0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
34c00 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69   are available i
34c10 6e 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  n the SQLite cor
34c20 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
34c30 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
34c40 55 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_OS2.** <li>
34c50 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
34c60 50 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20  PTHREAD.** <li> 
34c70 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57    SQLITE_MUTEX_W
34c80 33 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c  32.** <li>   SQL
34c90 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a  ITE_MUTEX_NOOP.*
34ca0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
34cb0 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  ^The SQLITE_MUTE
34cc0 58 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74  X_NOOP implement
34cd0 61 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f  ation is a set o
34ce0 66 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68  f routines.** th
34cf0 61 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20  at does no real 
34d00 6c 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61  locking and is a
34d10 70 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75  ppropriate for u
34d20 73 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c  se in.** a singl
34d30 65 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69  e-threaded appli
34d40 63 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51  cation.  ^The SQ
34d50 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a  LITE_MUTEX_OS2,.
34d60 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ** SQLITE_MUTEX_
34d70 50 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c  PTHREAD, and SQL
34d80 49 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d  ITE_MUTEX_W32 im
34d90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a  plementations.**
34da0 20 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65   are appropriate
34db0 20 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32   for use on OS/2
34dc0 2c 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64  , Unix, and Wind
34dd0 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ows..**.** ^(If 
34de0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
34df0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
34e00 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20  TE_MUTEX_APPDEF 
34e10 70 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20  preprocessor.** 
34e20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77  macro defined (w
34e30 69 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55  ith "-DSQLITE_MU
34e40 54 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20  TEX_APPDEF=1"), 
34e50 74 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a  then no mutex.**
34e60 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34e70 69 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68  is included with
34e80 20 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e   the library. In
34e90 20 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a   this case the.*
34ea0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  * application mu
34eb0 73 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74  st supply a cust
34ec0 6f 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  om mutex impleme
34ed0 6e 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68  ntation using th
34ee0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e.** [SQLITE_CON
34ef0 46 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f  FIG_MUTEX] optio
34f00 6e 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  n of the sqlite3
34f10 5f 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69  _config() functi
34f20 6f 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c  on.** before cal
34f30 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69  ling sqlite3_ini
34f40 74 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79  tialize() or any
34f50 20 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71   other public sq
34f60 6c 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69  lite3_.** functi
34f70 6f 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71  on that calls sq
34f80 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
34f90 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
34fa0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61   sqlite3_mutex_a
34fb0 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61  lloc() routine a
34fc0 6c 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a  llocates a new.*
34fd0 2a 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75  * mutex and retu
34fe0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
34ff0 20 69 74 2e 20 5e 49 66 20 69 74 20 72 65 74 75   it. ^If it retu
35000 72 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74  rns NULL.** that
35010 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75   means that a mu
35020 74 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65  tex could not be
35030 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51   allocated.  ^SQ
35040 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77  Lite.** will unw
35050 69 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e  ind its stack an
35060 64 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f  d return an erro
35070 72 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65  r.  ^(The argume
35080 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
35090 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69  _mutex_alloc() i
350a0 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
350b0 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
350c0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
350d0 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
350e0 45 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20  EX_FAST.** <li> 
350f0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
35100 43 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CURSIVE.** <li> 
35110 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
35120 41 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c  ATIC_MASTER.** <
35130 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
35140 58 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20  X_STATIC_MEM.** 
35150 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
35160 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a  EX_STATIC_MEM2.*
35170 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
35180 55 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47  UTEX_STATIC_PRNG
35190 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
351a0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
351b0 55 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  U.** <li>  SQLIT
351c0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
351d0 52 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  RU2.** </ul>)^.*
351e0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
351f0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28 53  two constants (S
35200 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
35210 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
35220 58 5f 52 45 43 55 52 53 49 56 45 29 0a 2a 2a 20  X_RECURSIVE).** 
35230 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75  cause sqlite3_mu
35240 74 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63  tex_alloc() to c
35250 72 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d  reate.** a new m
35260 75 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 77 20  utex.  ^The new 
35270 6d 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69  mutex is recursi
35280 76 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d  ve when SQLITE_M
35290 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
352a0 2a 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f  * is used but no
352b0 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f  t necessarily so
352c0 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
352d0 45 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e  EX_FAST is used.
352e0 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d  .** The mutex im
352f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65  plementation doe
35300 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61  s not need to ma
35310 6b 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e  ke a distinction
35320 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
35330 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
35340 56 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55  VE and SQLITE_MU
35350 54 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64  TEX_FAST if it d
35360 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
35370 74 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  to.  ^SQLite wil
35380 6c 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61  l only request a
35390 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
353a0 20 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65   in.** cases whe
353b0 72 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65  re it really nee
353c0 64 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20 66  ds one.  ^If a f
353d0 61 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73  aster non-recurs
353e0 69 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70  ive mutex.** imp
353f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
35400 76 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20  vailable on the 
35410 68 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74  host platform, t
35420 68 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74  he mutex subsyst
35430 65 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75  em.** might retu
35440 72 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20  rn such a mutex 
35450 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53  in response to S
35460 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54  QLITE_MUTEX_FAST
35470 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 68  ..**.** ^The oth
35480 65 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d  er allowed param
35490 65 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33  eters to sqlite3
354a0 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 28  _mutex_alloc() (
354b0 61 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 0a 2a  anything other.*
354c0 2a 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 55  * than SQLITE_MU
354d0 54 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c  TEX_FAST and SQL
354e0 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53  ITE_MUTEX_RECURS
354f0 49 56 45 29 20 65 61 63 68 20 72 65 74 75 72 6e  IVE) each return
35500 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
35510 20 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69   a static preexi
35520 73 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e 53  sting mutex.  ^S
35530 69 78 20 73 74 61 74 69 63 20 6d 75 74 65 78 65  ix static mutexe
35540 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79  s are.** used by
35550 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72   the current ver
35560 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20  sion of SQLite. 
35570 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
35580 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61   of SQLite.** ma
35590 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
355a0 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e   static mutexes.
355b0 20 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73    Static mutexes
355c0 20 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61   are for interna
355d0 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69  l.** use by SQLi
355e0 74 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63  te only.  Applic
355f0 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
35600 53 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73  SQLite mutexes s
35610 68 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c  hould.** use onl
35620 79 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75  y the dynamic mu
35630 74 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62  texes returned b
35640 79 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  y SQLITE_MUTEX_F
35650 41 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45  AST or.** SQLITE
35660 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
35670 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
35680 61 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65  at if one of the
35690 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70   dynamic mutex p
356a0 61 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54  arameters (SQLIT
356b0 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20  E_MUTEX_FAST.** 
356c0 6f 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  or SQLITE_MUTEX_
356d0 52 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73  RECURSIVE) is us
356e0 65 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ed then sqlite3_
356f0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a  mutex_alloc().**
35700 20 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65   returns a diffe
35710 72 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76  rent mutex on ev
35720 65 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74 20  ery call.  ^But 
35730 66 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a  for the static.*
35740 2a 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74  * mutex types, t
35750 68 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73  he same mutex is
35760 20 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65   returned on eve
35770 72 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73  ry call that has
35780 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70  .** the same typ
35790 65 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  e number..**.** 
357a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ^The sqlite3_mut
357b0 65 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  ex_free() routin
357c0 65 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20  e deallocates a 
357d0 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c  previously.** al
357e0 6c 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20  located dynamic 
357f0 6d 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 65 20  mutex.  ^SQLite 
35800 69 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65  is careful to de
35810 61 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a  allocate every.*
35820 2a 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20  * dynamic mutex 
35830 74 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65  that it allocate
35840 73 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20  s.  The dynamic 
35850 6d 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74  mutexes must not
35860 20 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68   be in.** use wh
35870 65 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c  en they are deal
35880 6c 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70  located.  Attemp
35890 74 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61  ting to dealloca
358a0 74 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d  te a static.** m
358b0 75 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20  utex results in 
358c0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
358d0 6f 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65 76  or.  ^SQLite nev
358e0 65 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a  er deallocates.*
358f0 2a 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78  * a static mutex
35900 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35910 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
35920 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d  () and sqlite3_m
35930 75 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69  utex_try() routi
35940 6e 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74  nes attempt.** t
35950 6f 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e  o enter a mutex.
35960 20 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 74 68    ^If another th
35970 72 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20  read is already 
35980 77 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78  within the mutex
35990 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  ,.** sqlite3_mut
359a0 65 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20  ex_enter() will 
359b0 62 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65  block and sqlite
359c0 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69  3_mutex_try() wi
359d0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ll return.** SQL
359e0 49 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 65 20  ITE_BUSY.  ^The 
359f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
35a00 79 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  y() interface re
35a10 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
35a20 5d 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73  ].** upon succes
35a30 73 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28 4d  sful entry.  ^(M
35a40 75 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75  utexes created u
35a50 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d  sing.** SQLITE_M
35a60 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63  UTEX_RECURSIVE c
35a70 61 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75  an be entered mu
35a80 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20  ltiple times by 
35a90 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e  the same thread.
35aa0 0a 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 73 65  .** In such case
35ab0 73 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20  s the,.** mutex 
35ac0 6d 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61  must be exited a
35ad0 6e 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f  n equal number o
35ae0 66 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61  f times before a
35af0 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
35b00 20 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20 5e   can enter.)^  ^
35b10 28 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 72  (If the same thr
35b20 65 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74  ead tries to ent
35b30 65 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  er any other.** 
35b40 6b 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f  kind of mutex mo
35b50 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68  re than once, th
35b60 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
35b70 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69  defined..** SQLi
35b80 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78  te will never ex
35b90 68 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65  hibit.** such be
35ba0 68 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77  havior in its ow
35bb0 6e 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73  n use of mutexes
35bc0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65  .)^.**.** ^(Some
35bd0 20 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78   systems (for ex
35be0 61 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39  ample, Windows 9
35bf0 35 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72  5) do not suppor
35c00 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  t the operation.
35c10 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  ** implemented b
35c20 79 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  y sqlite3_mutex_
35c30 74 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65  try().  On those
35c40 20 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65   systems, sqlite
35c50 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a  3_mutex_try().**
35c60 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
35c70 75 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  urn SQLITE_BUSY.
35c80 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
35c90 65 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73  e only ever uses
35ca0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
35cb0 78 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70  x_try() as an op
35cc0 74 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68  timization so th
35cd0 69 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  is is acceptable
35ce0 20 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a   behavior.)^.**.
35cf0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35d00 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f  mutex_leave() ro
35d10 75 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75  utine exits a mu
35d20 74 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20  tex that was.** 
35d30 70 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72  previously enter
35d40 65 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  ed by the same t
35d50 68 72 65 61 64 2e 20 20 20 5e 28 54 68 65 20 62  hread.   ^(The b
35d60 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e  ehavior.** is un
35d70 64 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d  defined if the m
35d80 75 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72  utex is not curr
35d90 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79  ently entered by
35da0 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20   the.** calling 
35db0 74 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74  thread or is not
35dc0 20 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63   currently alloc
35dd0 61 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69  ated.  SQLite wi
35de0 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65  ll.** never do e
35df0 69 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ither.)^.**.** ^
35e00 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
35e10 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
35e20 5f 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65  _enter(), sqlite
35e30 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f  3_mutex_try(), o
35e40 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74  r.** sqlite3_mut
35e50 65 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20  ex_leave() is a 
35e60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
35e70 65 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75  en all three rou
35e80 74 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20  tines.** behave 
35e90 61 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a  as no-ops..**.**
35ea0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
35eb0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
35ec0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d  ] and [sqlite3_m
35ed0 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e  utex_notheld()].
35ee0 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65  .*/.sqlite3_mute
35ef0 78 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  x *sqlite3_mutex
35f00 5f 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  _alloc(int);.voi
35f10 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
35f20 66 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74  free(sqlite3_mut
35f30 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ex*);.void sqlit
35f40 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73  e3_mutex_enter(s
35f50 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
35f60 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  int sqlite3_mute
35f70 78 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75  x_try(sqlite3_mu
35f80 74 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  tex*);.void sqli
35f90 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
35fa0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b  sqlite3_mutex*);
35fb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35fc0 3a 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20  : Mutex Methods 
35fd0 4f 62 6a 65 63 74 0a 2a 2a 20 45 58 50 45 52 49  Object.** EXPERI
35fe0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20  MENTAL.**.** An 
35ff0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
36000 20 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e   structure defin
36010 65 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c  es the low-level
36020 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65   routines.** use
36030 64 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e  d to allocate an
36040 64 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a  d use mutexes..*
36050 2a 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68  *.** Usually, th
36060 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20  e default mutex 
36070 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
36080 70 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69  provided by SQLi
36090 74 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63  te are.** suffic
360a0 69 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68  ient, however th
360b0 65 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f  e user has the o
360c0 70 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74  ption of substit
360d0 75 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a  uting a custom.*
360e0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
360f0 20 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64   for specialized
36100 20 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20   deployments or 
36110 73 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63  systems for whic
36120 68 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73  h SQLite.** does
36130 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73   not provide a s
36140 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
36150 74 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20  tation. In this 
36160 63 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a  case, the user.*
36170 2a 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f  * creates and po
36180 70 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61  pulates an insta
36190 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75  nce of this stru
361a0 63 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a  cture to pass.**
361b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
361c0 69 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20  ig() along with 
361d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
361e0 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  IG_MUTEX] option
361f0 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ..** Additionall
36200 79 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  y, an instance o
36210 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
36220 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
36230 61 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72  an.** output var
36240 69 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79  iable when query
36250 69 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66  ing the system f
36260 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d  or the current m
36270 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
36280 74 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68  tation, using th
36290 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
362a0 5f 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f  _GETMUTEX] optio
362b0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d  n..**.** ^The xM
362c0 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  utexInit method 
362d0 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20  defined by this 
362e0 73 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76  structure is inv
362f0 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  oked as.** part 
36300 6f 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61  of system initia
36310 6c 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20  lization by the 
36320 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
36330 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ze() function..*
36340 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69  * ^The xMutexIni
36350 74 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  t routine is cal
36360 6c 65 20 62 79 20 53 51 4c 69 74 65 20 65 78 61  le by SQLite exa
36370 63 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61  ctly once for ea
36380 63 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20  ch.** effective 
36390 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
363a0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a  _initialize()]..
363b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65  **.** ^The xMute
363c0 78 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69  xEnd method defi
363d0 6e 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75  ned by this stru
363e0 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64  cture is invoked
363f0 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73   as.** part of s
36400 79 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62  ystem shutdown b
36410 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68  y the sqlite3_sh
36420 75 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f  utdown() functio
36430 6e 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  n. The.** implem
36440 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73  entation of this
36450 20 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 63   method is expec
36460 74 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61  ted to release a
36470 6c 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a  ll outstanding.*
36480 2a 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61  * resources obta
36490 69 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 65  ined by the mute
364a0 78 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d  x methods implem
364b0 65 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69  entation, especi
364c0 61 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62  ally.** those ob
364d0 74 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d  tained by the xM
364e0 75 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e  utexInit method.
364f0 20 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64    ^The xMutexEnd
36500 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
36510 69 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74  is invoked exact
36520 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ly once for each
36530 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
36540 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
36550 2a 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61 69  *.** ^(The remai
36560 6e 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f  ning seven metho
36570 64 73 20 64 65 66 69 6e 65 64 20 62 79 20 74 68  ds defined by th
36580 69 73 20 73 74 72 75 63 74 75 72 65 20 28 78 4d  is structure (xM
36590 75 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d  utexAlloc,.** xM
365a0 75 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78  utexFree, xMutex
365b0 45 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79  Enter, xMutexTry
365c0 2c 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78  , xMutexLeave, x
365d0 4d 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a  MutexHeld and.**
365e0 20 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20   xMutexNotheld) 
365f0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f  implement the fo
36600 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63  llowing interfac
36610 65 73 20 28 72 65 73 70 65 63 74 69 76 65 6c 79  es (respectively
36620 29 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ):.**.** <ul>.**
36630 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
36640 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d  3_mutex_alloc()]
36650 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
36660 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
36670 5f 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  _free()] </li>.*
36680 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
36690 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
366a0 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
366b0 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
366c0 78 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  x_try()] </li>.*
366d0 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
366e0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29  e3_mutex_leave()
366f0 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69  ] </li>.**   <li
36700 3e 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  >  [sqlite3_mute
36710 78 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a  x_held()] </li>.
36720 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69  **   <li>  [sqli
36730 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
36740 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  d()] </li>.** </
36750 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
36760 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20  only difference 
36770 69 73 20 74 68 61 74 20 74 68 65 20 70 75 62 6c  is that the publ
36780 69 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66  ic sqlite3_XXX f
36790 75 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61  unctions enumera
367a0 74 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c  ted.** above sil
367b0 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79  ently ignore any
367c0 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61   invocations tha
367d0 74 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f  t pass a NULL po
367e0 69 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  inter instead.**
367f0 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
36800 78 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d  x handle. The im
36810 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
36820 20 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66   the methods def
36830 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20  ined.** by this 
36840 73 74 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f  structure are no
36850 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 61  t required to ha
36860 6e 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20  ndle this case, 
36870 74 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f  the results.** o
36880 66 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c  f passing a NULL
36890 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64   pointer instead
368a0 20 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65   of a valid mute
368b0 78 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64  x handle are und
368c0 65 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20  efined.** (i.e. 
368d0 69 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65  it is acceptable
368e0 20 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69   to provide an i
368f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
36900 61 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a  at segfaults if.
36910 2a 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 20  ** it is passed 
36920 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e  a NULL pointer).
36930 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65  .**.** The xMute
36940 78 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 6d  xInit() method m
36950 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
36960 65 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 65 20  e.  ^It must be 
36970 68 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 69  harmless to.** i
36980 6e 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 74  nvoke xMutexInit
36990 28 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 73  () mutiple times
369a0 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
369b0 20 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69 74   process and wit
369c0 68 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 6e  hout.** interven
369d0 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d 75  ing calls to xMu
369e0 74 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f 6e  texEnd().  Secon
369f0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
36a00 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75   calls to.** xMu
36a10 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 62  texInit() must b
36a20 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  e no-ops..**.** 
36a30 5e 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75  ^xMutexInit() mu
36a40 73 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74  st not use SQLit
36a50 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
36a60 69 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61  ion ([sqlite3_ma
36a70 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69  lloc()].** and i
36a80 74 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20  ts associates). 
36a90 20 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75   ^Similarly, xMu
36aa0 74 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20  texAlloc() must 
36ab0 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d  not use SQLite m
36ac0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
36ad0 69 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63  ion for a static
36ae0 20 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 76 65   mutex.  ^Howeve
36af0 72 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20  r xMutexAlloc() 
36b00 6d 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a  may use SQLite.*
36b10 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
36b20 69 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f  ion for a fast o
36b30 72 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65  r recursive mute
36b40 78 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  x..**.** ^SQLite
36b50 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
36b60 20 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74   xMutexEnd() met
36b70 68 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  hod when [sqlite
36b80 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73  3_shutdown()] is
36b90 0a 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20  .** called, but 
36ba0 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f  only if the prio
36bb0 72 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78  r call to xMutex
36bc0 49 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53 51  Init returned SQ
36bd0 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78  LITE_OK..** If x
36be0 4d 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20  MutexInit fails 
36bf0 69 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69  in any way, it i
36c00 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c  s expected to cl
36c10 65 61 6e 20 75 70 20 61 66 74 65 72 20 69 74 73  ean up after its
36c20 65 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  elf.** prior to 
36c30 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79  returning..*/.ty
36c40 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
36c50 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
36c60 64 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ds sqlite3_mutex
36c70 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
36c80 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
36c90 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28  ethods {.  int (
36ca0 2a 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69  *xMutexInit)(voi
36cb0 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  d);.  int (*xMut
36cc0 65 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20  exEnd)(void);.  
36cd0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28  sqlite3_mutex *(
36ce0 2a 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e  *xMutexAlloc)(in
36cf0 74 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75  t);.  void (*xMu
36d00 74 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33  texFree)(sqlite3
36d10 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69  _mutex *);.  voi
36d20 64 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29  d (*xMutexEnter)
36d30 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a  (sqlite3_mutex *
36d40 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
36d50 78 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75  xTry)(sqlite3_mu
36d60 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28  tex *);.  void (
36d70 2a 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71  *xMutexLeave)(sq
36d80 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a  lite3_mutex *);.
36d90 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65    int (*xMutexHe
36da0 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ld)(sqlite3_mute
36db0 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d  x *);.  int (*xM
36dc0 75 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c  utexNotheld)(sql
36dd0 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d  ite3_mutex *);.}
36de0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
36df0 46 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63  F: Mutex Verific
36e00 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a  ation Routines.*
36e10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
36e20 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e  _mutex_held() an
36e30 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
36e40 6e 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e  notheld() routin
36e50 65 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64  es.** are intend
36e60 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
36e70 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
36e80 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 51 4c  ments.  ^The SQL
36e90 69 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65  ite core.** neve
36ea0 72 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75  r uses these rou
36eb0 74 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73  tines except ins
36ec0 69 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20  ide an assert() 
36ed0 61 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  and applications
36ee0 0a 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20  .** are advised 
36ef0 74 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65  to follow the le
36f00 61 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20  ad of the core. 
36f10 20 5e 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72   ^The SQLite cor
36f20 65 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64  e only.** provid
36f30 65 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  es implementatio
36f40 6e 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75  ns for these rou
36f50 74 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73  tines when it is
36f60 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
36f70 68 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42  h the SQLITE_DEB
36f80 55 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 65 72  UG flag.  ^Exter
36f90 6e 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d  nal mutex implem
36fa0 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65  entations.** are
36fb0 20 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74   only required t
36fc0 6f 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20  o provide these 
36fd0 72 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49  routines if SQLI
36fe0 54 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64  TE_DEBUG is.** d
36ff0 65 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44  efined and if ND
37000 45 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69  EBUG is not defi
37010 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
37020 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  e routines shoul
37030 64 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66  d return true if
37040 20 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68   the mutex in th
37050 65 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  eir argument.** 
37060 69 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68  is held or not h
37070 65 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c  eld, respectivel
37080 79 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e  y, by the callin
37090 67 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  g thread..**.** 
370a0 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ^The implementat
370b0 69 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69  ion is not requi
370c0 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20  red to provided 
370d0 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73  versions of thes
370e0 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  e.** routines th
370f0 61 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b  at actually work
37100 2e 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65  . If the impleme
37110 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ntation does not
37120 20 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67   provide working
37130 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
37140 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
37150 69 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61  it should at lea
37160 73 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73  st provide stubs
37170 20 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20   that always.** 
37180 72 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74  return true so t
37190 68 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74  hat one does not
371a0 20 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 73   get spurious as
371b0 73 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  sertion failures
371c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
371d0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
371e0 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29  te3_mutex_held()
371f0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
37200 65 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  er then.** the r
37210 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65  outine should re
37220 74 75 72 6e 20 31 2e 20 20 20 54 68 69 73 20 73  turn 1.   This s
37230 65 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74  eems counter-int
37240 75 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20  uitive since.** 
37250 63 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65  clearly the mute
37260 78 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64  x cannot be held
37270 20 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20   if it does not 
37280 65 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a  exist.  But the.
37290 2a 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68  ** the reason th
372a0 65 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74  e mutex does not
372b0 20 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73   exist is becaus
372c0 65 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e  e the build is n
372d0 6f 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65  ot.** using mute
372e0 78 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20  xes.  And we do 
372f0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73  not want the ass
37300 65 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67  ert() containing
37310 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20   the.** call to 
37320 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
37330 6c 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f  ld() to fail, so
37340 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
37350 72 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70  rn is.** the app
37360 72 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74  ropriate thing t
37370 6f 20 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  o do.  ^The sqli
37380 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c  te3_mutex_nothel
37390 64 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  d().** interface
373a0 20 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74   should also ret
373b0 75 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e  urn 1 when given
373c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
373d0 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42  .*/.#ifndef NDEB
373e0 55 47 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  UG.int sqlite3_m
373f0 75 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65  utex_held(sqlite
37400 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73  3_mutex*);.int s
37410 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74  qlite3_mutex_not
37420 68 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74  held(sqlite3_mut
37430 65 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  ex*);.#endif../*
37440 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
37450 74 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20  tex Types.**.** 
37460 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  The [sqlite3_mut
37470 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65  ex_alloc()] inte
37480 72 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69  rface takes a si
37490 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  ngle argument.**
374a0 20 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66   which is one of
374b0 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   these integer c
374c0 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
374d0 54 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 69  The set of stati
374e0 63 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68  c mutexes may ch
374f0 61 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51  ange from one SQ
37500 4c 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20  Lite release to 
37510 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
37520 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
37530 6f 76 65 72 72 69 64 65 20 74 68 65 20 62 75 69  override the bui
37540 6c 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69  lt-in mutex logi
37550 63 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65  c must be.** pre
37560 70 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f  pared to accommo
37570 64 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  date additional 
37580 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a  static mutexes..
37590 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
375a0 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20  E_MUTEX_FAST    
375b0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
375c0 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
375d0 52 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20  RECURSIVE       
375e0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
375f0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
37600 41 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 69  ASTER    2.#defi
37610 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
37620 53 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20  STATIC_MEM      
37630 20 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   3  /* sqlite3_m
37640 61 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69  alloc() */.#defi
37650 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  ne SQLITE_MUTEX_
37660 53 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20  STATIC_MEM2     
37670 20 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20   4  /* NOT USED 
37680 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
37690 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f  E_MUTEX_STATIC_O
376a0 50 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73  PEN      4  /* s
376b0 71 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28  qlite3BtreeOpen(
376c0 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
376d0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
376e0 5f 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a  _PRNG      5  /*
376f0 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28   sqlite3_random(
37700 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
37710 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
37720 5f 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a  _LRU       6  /*
37730 20 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a   lru page list *
37740 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
37750 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
37760 55 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72  U2      7  /* lr
37770 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a  u page list */..
37780 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37790 52 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 74  Retrieve the mut
377a0 65 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 73  ex for a databas
377b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e connection.**.
377c0 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
377d0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
377e0 6e 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 65  nter the [sqlite
377f0 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 20  3_mutex] object 
37800 74 68 61 74 20 0a 2a 2a 20 73 65 72 69 61 6c 69  that .** seriali
37810 7a 65 73 20 61 63 63 65 73 73 20 74 6f 20 74 68  zes access to th
37820 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37830 65 63 74 69 6f 6e 5d 20 67 69 76 65 6e 20 69 6e  ection] given in
37840 20 74 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   the argument.**
37850 20 77 68 65 6e 20 74 68 65 20 5b 74 68 72 65 61   when the [threa
37860 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 53 65  ding mode] is Se
37870 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e 49 66  rialized..** ^If
37880 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
37890 6d 6f 64 65 5d 20 69 73 20 53 69 6e 67 6c 65 2d  mode] is Single-
378a0 74 68 72 65 61 64 20 6f 72 20 4d 75 6c 74 69 2d  thread or Multi-
378b0 74 68 72 65 61 64 20 74 68 65 6e 20 74 68 69 73  thread then this
378c0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
378d0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
378e0 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d  er..*/.sqlite3_m
378f0 75 74 65 78 20 2a 73 71 6c 69 74 65 33 5f 64 62  utex *sqlite3_db
37900 5f 6d 75 74 65 78 28 73 71 6c 69 74 65 33 2a 29  _mutex(sqlite3*)
37910 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37920 46 3a 20 4c 6f 77 2d 4c 65 76 65 6c 20 43 6f 6e  F: Low-Level Con
37930 74 72 6f 6c 20 4f 66 20 44 61 74 61 62 61 73 65  trol Of Database
37940 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Files.**.** ^Th
37950 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
37960 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
37970 66 61 63 65 20 6d 61 6b 65 73 20 61 20 64 69 72  face makes a dir
37980 65 63 74 20 63 61 6c 6c 20 74 6f 20 74 68 65 0a  ect call to the.
37990 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  ** xFileControl 
379a0 6d 65 74 68 6f 64 20 66 6f 72 20 74 68 65 20 5b  method for the [
379b0 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
379c0 64 73 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  ds] object assoc
379d0 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 61 20  iated.** with a 
379e0 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
379f0 61 73 65 20 69 64 65 6e 74 69 66 69 65 64 20 62  ase identified b
37a00 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  y the second arg
37a10 75 6d 65 6e 74 2e 20 5e 54 68 65 0a 2a 2a 20 6e  ument. ^The.** n
37a20 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
37a30 61 73 65 20 22 6d 61 69 6e 22 20 66 6f 72 20 74  ase "main" for t
37a40 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
37a50 20 6f 72 20 22 74 65 6d 70 22 20 66 6f 72 20 74   or "temp" for t
37a60 68 65 0a 2a 2a 20 54 45 4d 50 20 64 61 74 61 62  he.** TEMP datab
37a70 61 73 65 2c 20 6f 72 20 74 68 65 20 6e 61 6d 65  ase, or the name
37a80 20 74 68 61 74 20 61 70 70 65 61 72 73 20 61 66   that appears af
37a90 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f  ter the AS keywo
37aa0 72 64 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  rd for.** databa
37ab0 73 65 73 20 74 68 61 74 20 61 72 65 20 61 64 64  ses that are add
37ac0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 41 54  ed using the [AT
37ad0 54 41 43 48 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e  TACH] SQL comman
37ae0 64 2e 0a 2a 2a 20 5e 41 20 4e 55 4c 4c 20 70 6f  d..** ^A NULL po
37af0 69 6e 74 65 72 20 63 61 6e 20 62 65 20 75 73 65  inter can be use
37b00 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d  d in place of "m
37b10 61 69 6e 22 20 74 6f 20 72 65 66 65 72 20 74 6f  ain" to refer to
37b20 20 74 68 65 0a 2a 2a 20 6d 61 69 6e 20 64 61 74   the.** main dat
37b30 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 20 5e  abase file..** ^
37b40 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
37b50 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20  urth parameters 
37b60 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a  to this routine.
37b70 2a 2a 20 61 72 65 20 70 61 73 73 65 64 20 64 69  ** are passed di
37b80 72 65 63 74 6c 79 20 74 68 72 6f 75 67 68 20 74  rectly through t
37b90 6f 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  o the second and
37ba0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
37bb0 73 20 6f 66 0a 2a 2a 20 74 68 65 20 78 46 69 6c  s of.** the xFil
37bc0 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 2e  eControl method.
37bd0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61    ^The return va
37be0 6c 75 65 20 6f 66 20 74 68 65 20 78 46 69 6c 65  lue of the xFile
37bf0 43 6f 6e 74 72 6f 6c 0a 2a 2a 20 6d 65 74 68 6f  Control.** metho
37c00 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20 72 65  d becomes the re
37c10 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
37c20 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a  is routine..**.*
37c30 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64  * ^If the second
37c40 20 70 61 72 61 6d 65 74 65 72 20 28 7a 44 62 4e   parameter (zDbN
37c50 61 6d 65 29 20 64 6f 65 73 20 6e 6f 74 20 6d 61  ame) does not ma
37c60 74 63 68 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  tch the name of 
37c70 61 6e 79 0a 2a 2a 20 6f 70 65 6e 20 64 61 74 61  any.** open data
37c80 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65 6e 20  base file, then 
37c90 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69 73 20  SQLITE_ERROR is 
37ca0 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 69 73  returned.  ^This
37cb0 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
37cc0 73 20 6e 6f 74 20 72 65 6d 65 6d 62 65 72 65 64  s not remembered
37cd0 20 61 6e 64 20 77 69 6c 6c 20 6e 6f 74 20 62 65   and will not be
37ce0 20 72 65 63 61 6c 6c 65 64 20 62 79 20 5b 73 71   recalled by [sq
37cf0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
37d00 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
37d10 65 72 72 6d 73 67 28 29 5d 2e 20 20 54 68 65 20  errmsg()].  The 
37d20 75 6e 64 65 72 6c 79 69 6e 67 20 78 46 69 6c 65  underlying xFile
37d30 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 6d  Control method m
37d40 69 67 68 74 0a 2a 2a 20 61 6c 73 6f 20 72 65 74  ight.** also ret
37d50 75 72 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  urn SQLITE_ERROR
37d60 2e 20 20 54 68 65 72 65 20 69 73 20 6e 6f 20 77  .  There is no w
37d70 61 79 20 74 6f 20 64 69 73 74 69 6e 67 75 69 73  ay to distinguis
37d80 68 20 62 65 74 77 65 65 6e 0a 2a 2a 20 61 6e 20  h between.** an 
37d90 69 6e 63 6f 72 72 65 63 74 20 7a 44 62 4e 61 6d  incorrect zDbNam
37da0 65 20 61 6e 64 20 61 6e 20 53 51 4c 49 54 45 5f  e and an SQLITE_
37db0 45 52 52 4f 52 20 72 65 74 75 72 6e 20 66 72 6f  ERROR return fro
37dc0 6d 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  m the underlying
37dd0 0a 2a 2a 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  .** xFileControl
37de0 20 6d 65 74 68 6f 64 2e 0a 2a 2a 0a 2a 2a 20 53   method..**.** S
37df0 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
37e00 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
37e10 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
37e20 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 73 71  _file_control(sq
37e30 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
37e40 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 69 6e 74  ar *zDbName, int
37e50 20 6f 70 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   op, void*);../*
37e60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
37e70 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63 65 0a  sting Interface.
37e80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37e90 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28  e3_test_control(
37ea0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
37eb0 73 65 64 20 74 6f 20 72 65 61 64 20 6f 75 74 20  sed to read out 
37ec0 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 73 74 61 74  internal.** stat
37ed0 65 20 6f 66 20 53 51 4c 69 74 65 20 61 6e 64 20  e of SQLite and 
37ee0 74 6f 20 69 6e 6a 65 63 74 20 66 61 75 6c 74 73  to inject faults
37ef0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 66 6f 72   into SQLite for
37f00 20 74 65 73 74 69 6e 67 0a 2a 2a 20 70 75 72 70   testing.** purp
37f10 6f 73 65 73 2e 20 20 5e 54 68 65 20 66 69 72 73  oses.  ^The firs
37f20 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
37f30 6e 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65  n operation code
37f40 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
37f50 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 2c 20  .** the number, 
37f60 6d 65 61 6e 69 6e 67 2c 20 61 6e 64 20 6f 70 65  meaning, and ope
37f70 72 61 74 69 6f 6e 20 6f 66 20 61 6c 6c 20 73 75  ration of all su
37f80 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
37f90 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ers..**.** This 
37fa0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
37fb0 20 66 6f 72 20 75 73 65 20 62 79 20 61 70 70 6c   for use by appl
37fc0 69 63 61 74 69 6f 6e 73 2e 20 20 49 74 20 65 78  ications.  It ex
37fd0 69 73 74 73 20 73 6f 6c 65 6c 79 0a 2a 2a 20 66  ists solely.** f
37fe0 6f 72 20 76 65 72 69 66 79 69 6e 67 20 74 68 65  or verifying the
37ff0 20 63 6f 72 72 65 63 74 20 6f 70 65 72 61 74 69   correct operati
38000 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
38010 20 6c 69 62 72 61 72 79 2e 20 20 44 65 70 65 6e   library.  Depen
38020 64 69 6e 67 0a 2a 2a 20 6f 6e 20 68 6f 77 20 74  ding.** on how t
38030 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
38040 79 20 69 73 20 63 6f 6d 70 69 6c 65 64 2c 20 74  y is compiled, t
38050 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6d 69  his interface mi
38060 67 68 74 20 6e 6f 74 20 65 78 69 73 74 2e 0a 2a  ght not exist..*
38070 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
38080 20 6f 66 20 74 68 65 20 6f 70 65 72 61 74 69 6f   of the operatio
38090 6e 20 63 6f 64 65 73 2c 20 74 68 65 69 72 20 6d  n codes, their m
380a0 65 61 6e 69 6e 67 73 2c 20 74 68 65 20 70 61 72  eanings, the par
380b0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 68 65 79 20  ameters.** they 
380c0 74 61 6b 65 2c 20 61 6e 64 20 77 68 61 74 20 74  take, and what t
380d0 68 65 79 20 64 6f 20 61 72 65 20 61 6c 6c 20 73  hey do are all s
380e0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
380f0 20 77 69 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e   without notice.
38100 0a 2a 2a 20 55 6e 6c 69 6b 65 20 6d 6f 73 74 20  .** Unlike most 
38110 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 41 50  of the SQLite AP
38120 49 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  I, this function
38130 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
38140 65 64 20 74 6f 0a 2a 2a 20 6f 70 65 72 61 74 65  ed to.** operate
38150 20 63 6f 6e 73 69 73 74 65 6e 74 6c 79 20 66 72   consistently fr
38160 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
38170 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 69  o the next..*/.i
38180 6e 74 20 73 71 6c 69 74 65 33 5f 74 65 73 74 5f  nt sqlite3_test_
38190 63 6f 6e 74 72 6f 6c 28 69 6e 74 20 6f 70 2c 20  control(int op, 
381a0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
381b0 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49  I3REF: Testing I
381c0 6e 74 65 72 66 61 63 65 20 4f 70 65 72 61 74 69  nterface Operati
381d0 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  on Codes.**.** T
381e0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
381f0 72 65 20 74 68 65 20 76 61 6c 69 64 20 6f 70 65  re the valid ope
38200 72 61 74 69 6f 6e 20 63 6f 64 65 20 70 61 72 61  ration code para
38210 6d 65 74 65 72 73 20 75 73 65 64 0a 2a 2a 20 61  meters used.** a
38220 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
38230 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
38240 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _test_control()]
38250 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 70 61  ..**.** These pa
38260 72 61 6d 65 74 65 72 73 20 61 6e 64 20 74 68 65  rameters and the
38270 69 72 20 6d 65 61 6e 69 6e 67 73 20 61 72 65 20  ir meanings are 
38280 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
38290 65 0a 2a 2a 20 77 69 74 68 6f 75 74 20 6e 6f 74  e.** without not
382a0 69 63 65 2e 20 20 54 68 65 73 65 20 76 61 6c 75  ice.  These valu
382b0 65 73 20 61 72 65 20 66 6f 72 20 74 65 73 74 69  es are for testi
382c0 6e 67 20 70 75 72 70 6f 73 65 73 20 6f 6e 6c 79  ng purposes only
382d0 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
382e0 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65  s should not use
382f0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 70 61   any of these pa
38300 72 61 6d 65 74 65 72 73 20 6f 72 20 74 68 65 0a  rameters or the.
38310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74  ** [sqlite3_test
38320 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
38330 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  rface..*/.#defin
38340 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52  e SQLITE_TESTCTR
38350 4c 5f 50 52 4e 47 5f 53 41 56 45 20 20 20 20 20  L_PRNG_SAVE     
38360 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
38370 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54  fine SQLITE_TEST
38380 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53 54 4f 52  CTRL_PRNG_RESTOR
38390 45 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a  E             6.
383a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
383b0 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f 52 45 53  ESTCTRL_PRNG_RES
383c0 45 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ET              
383d0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
383e0 45 5f 54 45 53 54 43 54 52 4c 5f 42 49 54 56 45  E_TESTCTRL_BITVE
383f0 43 5f 54 45 53 54 20 20 20 20 20 20 20 20 20 20  C_TEST          
38400 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
38410 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 46 41  LITE_TESTCTRL_FA
38420 55 4c 54 5f 49 4e 53 54 41 4c 4c 20 20 20 20 20  ULT_INSTALL     
38430 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
38440 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
38450 5f 42 45 4e 49 47 4e 5f 4d 41 4c 4c 4f 43 5f 48  _BENIGN_MALLOC_H
38460 4f 4f 4b 53 20 20 20 20 20 31 30 0a 23 64 65 66  OOKS     10.#def
38470 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
38480 54 52 4c 5f 50 45 4e 44 49 4e 47 5f 42 59 54 45  TRL_PENDING_BYTE
38490 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
384a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
384b0 53 54 43 54 52 4c 5f 41 53 53 45 52 54 20 20 20  STCTRL_ASSERT   
384c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
384d0 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
384e0 5f 54 45 53 54 43 54 52 4c 5f 41 4c 57 41 59 53  _TESTCTRL_ALWAYS
384f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38500 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
38510 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 52 45 53  ITE_TESTCTRL_RES
38520 45 52 56 45 20 20 20 20 20 20 20 20 20 20 20 20  ERVE            
38530 20 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43       14../*.** C
38540 41 50 49 33 52 45 46 3a 20 53 51 4c 69 74 65 20  API3REF: SQLite 
38550 52 75 6e 74 69 6d 65 20 53 74 61 74 75 73 0a 2a  Runtime Status.*
38560 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a  * EXPERIMENTAL.*
38570 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
38580 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
38590 72 65 74 72 69 65 76 65 20 72 75 6e 74 69 6d 65  retrieve runtime
385a0 20 73 74 61 74 75 73 20 69 6e 66 6f 72 6d 61 74   status informat
385b0 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ion.** about the
385c0 20 70 72 65 66 6f 72 6d 61 6e 63 65 20 6f 66 20   preformance of 
385d0 53 51 4c 69 74 65 2c 20 61 6e 64 20 6f 70 74 69  SQLite, and opti
385e0 6f 6e 61 6c 6c 79 20 74 6f 20 72 65 73 65 74 20  onally to reset 
385f0 76 61 72 69 6f 75 73 0a 2a 2a 20 68 69 67 68 77  various.** highw
38600 61 74 65 72 20 6d 61 72 6b 73 2e 20 20 5e 54 68  ater marks.  ^Th
38610 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
38620 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
38630 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ode for.** the s
38640 70 65 63 69 66 69 63 20 70 61 72 61 6d 65 74 65  pecific paramete
38650 72 20 74 6f 20 6d 65 61 73 75 72 65 2e 20 20 5e  r to measure.  ^
38660 52 65 63 6f 67 6e 69 7a 65 64 20 69 6e 74 65 67  Recognized integ
38670 65 72 20 63 6f 64 65 73 0a 2a 2a 20 61 72 65 20  er codes.** are 
38680 6f 66 20 74 68 65 20 66 6f 72 6d 20 5b 53 51 4c  of the form [SQL
38690 49 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52  ITE_STATUS_MEMOR
386a0 59 5f 55 53 45 44 20 7c 20 53 51 4c 49 54 45 5f  Y_USED | SQLITE_
386b0 53 54 41 54 55 53 5f 2e 2e 2e 5d 2e 0a 2a 2a 20  STATUS_...]..** 
386c0 5e 54 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c  ^The current val
386d0 75 65 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  ue of the parame
386e0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ter is returned 
386f0 69 6e 74 6f 20 2a 70 43 75 72 72 65 6e 74 2e 0a  into *pCurrent..
38700 2a 2a 20 5e 54 68 65 20 68 69 67 68 65 73 74 20  ** ^The highest 
38710 72 65 63 6f 72 64 65 64 20 76 61 6c 75 65 20 69  recorded value i
38720 73 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  s returned in *p
38730 48 69 67 68 77 61 74 65 72 2e 20 20 5e 49 66 20  Highwater.  ^If 
38740 74 68 65 0a 2a 2a 20 72 65 73 65 74 46 6c 61 67  the.** resetFlag
38750 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74   is true, then t
38760 68 65 20 68 69 67 68 65 73 74 20 72 65 63 6f 72  he highest recor
38770 64 20 76 61 6c 75 65 20 69 73 20 72 65 73 65 74  d value is reset
38780 20 61 66 74 65 72 0a 2a 2a 20 2a 70 48 69 67 68   after.** *pHigh
38790 77 61 74 65 72 20 69 73 20 77 72 69 74 74 65 6e  water is written
387a0 2e 20 20 5e 28 53 6f 6d 65 20 70 61 72 61 6d 65  .  ^(Some parame
387b0 74 65 72 73 20 64 6f 20 6e 6f 74 20 72 65 63 6f  ters do not reco
387c0 72 64 20 74 68 65 20 68 69 67 68 65 73 74 0a 2a  rd the highest.*
387d0 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68  * value.  For th
387e0 6f 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  ose parameters.*
387f0 2a 20 6e 6f 74 68 69 6e 67 20 69 73 20 77 72 69  * nothing is wri
38800 74 74 65 6e 20 69 6e 74 6f 20 2a 70 48 69 67 68  tten into *pHigh
38810 77 61 74 65 72 20 61 6e 64 20 74 68 65 20 72 65  water and the re
38820 73 65 74 46 6c 61 67 20 69 73 20 69 67 6e 6f 72  setFlag is ignor
38830 65 64 2e 29 5e 0a 2a 2a 20 5e 28 4f 74 68 65 72  ed.)^.** ^(Other
38840 20 70 61 72 61 6d 65 74 65 72 73 20 72 65 63 6f   parameters reco
38850 72 64 20 6f 6e 6c 79 20 74 68 65 20 68 69 67 68  rd only the high
38860 77 61 74 65 72 20 6d 61 72 6b 20 61 6e 64 20 6e  water mark and n
38870 6f 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  ot the current.*
38880 2a 20 76 61 6c 75 65 2e 20 20 46 6f 72 20 74 68  * value.  For th
38890 65 73 65 20 6c 61 74 74 65 72 20 70 61 72 61 6d  ese latter param
388a0 65 74 65 72 73 20 6e 6f 74 68 69 6e 67 20 69 73  eters nothing is
388b0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
388c0 43 75 72 72 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  Current.)^.**.**
388d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
388e0 5f 73 74 61 74 75 73 28 29 20 72 6f 75 74 69 6e  _status() routin
388f0 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  e returns SQLITE
38900 5f 4f 4b 20 6f 6e 20 73 75 63 63 65 73 73 20 61  _OK on success a
38910 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  nd a.**