/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 4d7bcef44286d9c2ff968be8f51fbbd2b7e9e492:


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 7b 45 4e 44 7d 20 20 54 68 65  ject. {END}  The
9190: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
91a0: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
91b0: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
91c0: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
91d0: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
91e0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
91f0: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
9200: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
9210: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
9220: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
9230: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
9240: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
9250: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
9260: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
9270: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
9280: 66 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61  file is both rea
9290: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
92a0: 6c 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  le..** With SQLI
92b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
92c0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
92d0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
92e0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
92f0: 20 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64   readable..*/.#d
9300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
9310: 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
9320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
9330: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
9340: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
9350: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20  _ACCESS_READ    
9360: 20 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    2../*.** CAPI3
9370: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
9380: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
9390: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
93a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
93b0: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
93c0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
93d0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
93e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
93f0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
9400: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
9410: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
9420: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
9430: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
9440: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
9450: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
9460: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
9470: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
9480: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
9490: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
94a0: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
94b0: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
94c0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
94d0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
94e0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
94f0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
9500: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
9510: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
9520: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
9530: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
9540: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
9550: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
9560: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
9570: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
9580: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
9590: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
95a0: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
95b0: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
95c0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
95d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
95e0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
95f0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
9600: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
9610: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
9620: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
9630: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
9640: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
9650: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
9660: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
9670: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
9680: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
9690: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
96a0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
96b0: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
96c0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
96d0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
96e0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
96f0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
9700: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
9710: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
9720: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
9730: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
9740: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9750: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
9760: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
9770: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
9780: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
9790: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
97a0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
97b0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
97c0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
97d0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
97e0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
97f0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
9800: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
9810: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
9820: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
9830: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
9840: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
9850: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
9860: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
9870: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
9880: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
9890: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
98a0: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
98b0: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
98c0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
98d0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
98e0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
98f0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
9900: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
9910: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
9920: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
9930: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
9940: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
9950: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
9960: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
9970: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
9980: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
9990: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
99a0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
99b0: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
99c0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
99d0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
99e0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
99f0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
9a00: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
9a10: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
9a20: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
9a30: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
9a40: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
9a50: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
9a60: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
9a70: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
9a80: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
9a90: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
9aa0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9ab0: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
9ac0: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
9ad0: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
9ae0: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
9af0: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
9b00: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
9b10: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
9b20: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
9b30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9b40: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
9b50: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
9b60: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
9b70: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
9b80: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
9b90: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
9ba0: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
9bb0: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
9bc0: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
9bd0: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
9be0: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
9bf0: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
9c00: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
9c10: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
9c20: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
9c30: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
9c40: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
9c50: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
9c60: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
9c70: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
9c80: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
9c90: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
9ca0: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
9cb0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
9cc0: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
9cd0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
9ce0: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
9cf0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
9d00: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
9d10: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
9d20: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
9d30: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
9d40: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
9d50: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
9d60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9d70: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
9d80: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
9d90: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
9da0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
9db0: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
9dc0: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
9dd0: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
9de0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
9df0: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
9e00: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
9e10: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
9e20: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
9e30: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
9e40: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
9e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
9e60: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
9e70: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
9e80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
9e90: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
9ea0: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
9eb0: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
9ec0: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
9ed0: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
9ee0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
9ef0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
9f00: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
9f10: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
9f20: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
9f30: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
9f40: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
9f50: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
9f60: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
9f70: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
9f80: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
9f90: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
9fa0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
9fb0: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
9fc0: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
9fd0: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
9fe0: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
9ff0: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
a000: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
a010: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
a020: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
a030: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
a040: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
a050: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
a060: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
a070: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
a080: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
a090: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
a0a0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
a0b0: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
a0c0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a0d0: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
a0e0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
a0f0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
a100: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
a110: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
a120: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
a130: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a140: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
a150: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
a160: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
a170: 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
a180: 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
a190: 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
a1a0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
a1b0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
a1c0: 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
a1d0: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
a1e0: 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
a1f0: 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
a200: 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
a210: 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
a220: 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
a230: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
a240: 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
a250: 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
a260: 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
a270: 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
a280: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
a290: 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
a2a0: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
a2b0: 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
a2c0: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
a2d0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
a2e0: 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
a2f0: 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
a300: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
a310: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
a320: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
a330: 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
a340: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
a350: 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
a360: 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
a370: 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
a380: 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
a390: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a3a0: 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
a3b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
a3c0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
a3d0: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
a3e0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
a3f0: 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
a400: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
a410: 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
a420: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 20 45 58 50  e Library.** EXP
a430: 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
a440: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
a450: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
a460: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
a470: 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
a480: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
a490: 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
a4a0: 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
a4b0: 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
a4c0: 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
a4d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
a4e0: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
a4f0: 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
a500: 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
a510: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
a520: 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
a530: 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
a540: 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
a550: 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
a560: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
a570: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
a580: 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
a590: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
a5a0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
a5b0: 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74  terface is not t
a5c0: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20  hreadsafe.  The 
a5d0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
a5e0: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
a5f0: 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
a600: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
a610: 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
a620: 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
a630: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
a640: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46  ) is running.  F
a650: 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69  urthermore, sqli
a660: 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20  te3_config().** 
a670: 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
a680: 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
a690: 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
a6a0: 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
a6b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
a6c0: 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
a6d0: 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
a6e0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
a6f0: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
a700: 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
a710: 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
a720: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
a730: 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
a740: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
a750: 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
a760: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
a770: 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
a780: 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
a790: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
a7a0: 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
a7b0: 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
a7c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
a7d0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
a7e0: 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
a7f0: 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
a800: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
a810: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
a820: 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
a830: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
a840: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
a850: 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61  READ | configura
a860: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
a870: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
a880: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
a890: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
a8a0: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
a8b0: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
a8c0: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
a8d0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c  ding on the [SQL
a8e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
a8f0: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67  ETHREAD | config
a900: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
a910: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
a920: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
a930: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
a940: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
a950: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
a960: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
a970: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
a980: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
a990: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
a9a0: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
a9b0: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
a9c0: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
a9d0: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
a9e0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
a9f0: 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  e]..*/.SQLITE_EX
aa00: 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73  PERIMENTAL int s
aa10: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
aa20: 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
aa30: 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
aa40: 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
aa50: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 45 58 50 45  nections.** EXPE
aa60: 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
aa70: 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
aa80: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
aa90: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
aaa0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
aab0: 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
aac0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
aad0: 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
aae0: 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
aaf0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
ab00: 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
ab10: 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
ab20: 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
ab30: 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
ab40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
ab50: 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
ab60: 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20 20  rst argument).  
ab70: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 64  The.** sqlite3_d
ab80: 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
ab90: 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  face should only
aba0: 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69 61   be used immedia
abb0: 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74 68  tely after.** th
abc0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
abd0: 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64  ction is created
abe0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
abf0: 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  open()],.** [sql
ac00: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
ac10: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
ac20: 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a 20  _v2()].  .**.** 
ac30: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
ac40: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
ac50: 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
ac60: 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6e  )  is the.** con
ac70: 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 20  figuration verb 
ac80: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
ac90: 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  e that indicates
aca0: 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74 20   what.** aspect 
acb0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
acc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
acd0: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
ace0: 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63 68  ..** The only ch
acf0: 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76 61  oice for this va
ad00: 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44  lue is [SQLITE_D
ad10: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
ad20: 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62 73  E]..** New verbs
ad30: 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 62   are likely to b
ad40: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
ad50: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
ad60: 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  Lite..** Additio
ad70: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64 65  nal arguments de
ad80: 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72 62  pend on the verb
ad90: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
ada0: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
adb0: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
adc0: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
add0: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
ade0: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
adf0: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2a 0a 2a  successful..**.*
ae00: 2a 20 52 65 71 75 69 72 65 6d 65 6e 74 73 3a 0a  * Requirements:.
ae10: 2a 2a 20 5b 48 31 34 32 30 33 5d 20 5b 48 31 34  ** [H14203] [H14
ae20: 32 30 36 5d 20 5b 48 31 34 32 30 39 5d 20 5b 48  206] [H14209] [H
ae30: 31 34 32 31 32 5d 20 5b 48 31 34 32 31 35 5d 0a  14212] [H14215].
ae40: 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49  */.SQLITE_EXPERI
ae50: 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74  MENTAL int sqlit
ae60: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
ae70: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
ae80: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
ae90: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
aea0: 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
aeb0: 20 7b 48 31 30 31 35 35 7d 20 3c 53 32 30 31 32   {H10155} <S2012
aec0: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
aed0: 41 4c 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  AL.**.** An inst
aee0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
aef0: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
af00: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
af10: 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
af20: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
af30: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
af40: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
af50: 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
af60: 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
af70: 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
af80: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
af90: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
afa0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
afb0: 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
afc0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
afd0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
afe0: 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
aff0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
b000: 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
b010: 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
b020: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
b030: 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
b040: 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
b050: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
b060: 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
b070: 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
b080: 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
b090: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
b0a0: 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
b0b0: 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
b0c0: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
b0d0: 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
b0e0: 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
b0f0: 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
b100: 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
b110: 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
b120: 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
b130: 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
b140: 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
b150: 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
b160: 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
b170: 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
b180: 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
b190: 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
b1a0: 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
b1b0: 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
b1c0: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
b1d0: 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
b1e0: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
b1f0: 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
b200: 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
b210: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
b220: 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
b230: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
b240: 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
b250: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
b260: 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
b270: 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
b280: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
b290: 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
b2a0: 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
b2b0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
b2c0: 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
b2d0: 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
b2e0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
b2f0: 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
b300: 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
b310: 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
b320: 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
b330: 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
b340: 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64   The xMalloc and
b350: 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
b360: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
b370: 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  e.** malloc() an
b380: 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
b390: 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
b3a0: 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
b3b0: 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20  ** The xRealloc 
b3c0: 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b  method must work
b3d0: 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20   like realloc() 
b3e0: 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
b3f0: 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77  d C library.** w
b400: 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f  ith the exceptio
b410: 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65  n that if the se
b420: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
b430: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72   xRealloc is zer
b440: 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d  o,.** xRealloc m
b450: 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d  ust be a no-op -
b460: 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72   it must not per
b470: 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74  form any allocat
b480: 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f  ion or.** deallo
b490: 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65  cation.  ^SQLite
b4a0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
b4b0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
b4c0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
b4d0: 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
b4e0: 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
b4f0: 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
b500: 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41  o xRoundup..** A
b510: 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77  nd so in cases w
b520: 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c  here xRoundup al
b530: 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70  ways returns a p
b540: 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a  ositive number,.
b550: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20  ** xRealloc can 
b560: 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20  perform exactly 
b570: 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  as the standard 
b580: 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28  library realloc(
b590: 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62  ) and.** still b
b5a0: 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20  e in compliance 
b5b0: 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66  with this specif
b5c0: 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78  ication..**.** x
b5d0: 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
b5e0: 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
b5f0: 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
b600: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
b610: 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
b620: 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
b630: 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
b640: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
b650: 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
b660: 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
b670: 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
b680: 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
b690: 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
b6a0: 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
b6b0: 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
b6c0: 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
b6d0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
b6e0: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
b6f0: 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
b700: 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
b710: 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
b720: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
b730: 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
b740: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
b750: 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
b760: 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
b770: 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
b780: 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
b790: 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
b7a0: 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
b7b0: 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
b7c0: 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
b7d0: 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
b7e0: 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
b7f0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
b800: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
b810: 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
b820: 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
b830: 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
b840: 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
b850: 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
b860: 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
b870: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
b880: 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
b890: 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
b8a0: 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
b8b0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
b8c0: 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
b8d0: 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
b8e0: 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
b8f0: 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
b900: 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
b910: 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
b920: 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
b930: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
b940: 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
b950: 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
b960: 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
b970: 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
b980: 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
b990: 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
b9a0: 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
b9b0: 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
b9c0: 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
b9d0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
b9e0: 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
b9f0: 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
ba00: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
ba10: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
ba20: 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
ba30: 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
ba40: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
ba50: 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
ba60: 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
ba70: 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
ba80: 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
ba90: 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
baa0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
bab0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
bac0: 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
bad0: 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
bae0: 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
baf0: 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
bb00: 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
bb10: 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
bb20: 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
bb30: 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
bb40: 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
bb50: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
bb60: 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
bb70: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
bb80: 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
bb90: 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
bba0: 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
bbb0: 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
bbc0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
bbd0: 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
bbe0: 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
bbf0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
bc00: 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
bc10: 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
bc20: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
bc30: 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
bc40: 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
bc50: 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
bc60: 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
bc70: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
bc80: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
bc90: 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
bca0: 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
bcb0: 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
bcc0: 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
bcd0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
bce0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
bcf0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
bd00: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
bd10: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
bd20: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
bd30: 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
bd40: 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
bd50: 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
bd60: 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
bd70: 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
bd80: 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
bd90: 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
bda0: 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
bdb0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
bdc0: 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
bdd0: 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
bde0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
bdf0: 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
be00: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
be10: 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
be20: 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
be30: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
be40: 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
be50: 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
be60: 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
be70: 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
be80: 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
be90: 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
bea0: 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
beb0: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
bec0: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
bed0: 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
bee0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
bef0: 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
bf00: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
bf10: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
bf20: 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
bf30: 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
bf40: 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
bf50: 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
bf60: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
bf70: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
bf80: 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 7b 48 31 30  ion Options {H10
bf90: 31 36 30 7d 20 3c 53 32 30 30 30 30 3e 0a 2a 2a  160} <S20000>.**
bfa0: 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
bfb0: 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
bfc0: 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
bfd0: 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
bfe0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
bff0: 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
c000: 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
c010: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
c020: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c030: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
c040: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
c050: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c060: 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
c070: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
c080: 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
c090: 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
c0a0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
c0b0: 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
c0c0: 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
c0d0: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
c0e0: 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
c0f0: 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
c100: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
c110: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
c120: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
c130: 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
c140: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
c150: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
c160: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
c170: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
c180: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
c190: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
c1a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c1b0: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
c1c0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
c1d0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
c1e0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
c1f0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
c200: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
c210: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
c220: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
c230: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
c240: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
c250: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
c260: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
c270: 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
c280: 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
c290: 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
c2a0: 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
c2b0: 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
c2c0: 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
c2d0: 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
c2e0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
c2f0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
c300: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
c310: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
c320: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
c330: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
c340: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
c350: 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
c360: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
c370: 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
c380: 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
c390: 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
c3a0: 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
c3b0: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
c3c0: 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
c3d0: 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
c3e0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
c3f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
c400: 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
c410: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
c420: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
c430: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
c440: 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
c450: 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
c460: 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
c470: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
c480: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
c490: 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
c4a0: 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
c4b0: 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
c4c0: 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
c4d0: 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
c4e0: 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
c4f0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
c500: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
c510: 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
c520: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
c530: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
c540: 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
c550: 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
c560: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c570: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
c580: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
c590: 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
c5a0: 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
c5b0: 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
c5c0: 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
c5d0: 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
c5e0: 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
c5f0: 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
c600: 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
c610: 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
c620: 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
c630: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
c640: 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
c650: 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
c660: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
c670: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
c680: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
c690: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
c6a0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
c6b0: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
c6c0: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
c6d0: 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
c6e0: 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
c6f0: 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
c700: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
c710: 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
c720: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
c730: 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
c740: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
c750: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
c760: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c770: 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
c780: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
c790: 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74  G_SERIALIZED</dt
c7a0: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
c7b0: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
c7c0: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
c7d0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
c7e0: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
c7f0: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65  ding mode] to Se
c800: 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68  rialized. In oth
c810: 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f  er words, this o
c820: 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a  ption enables.**
c830: 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63   all mutexes inc
c840: 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72  luding the recur
c850: 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20  sive.** mutexes 
c860: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
c870: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
c880: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
c890: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e  ] objects..** In
c8a0: 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63   this mode (whic
c8b0: 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  h is the default
c8c0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
c8d0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
c8e0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
c8f0: 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69  AFE=1]) the SQLi
c900: 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
c910: 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65  itself serialize
c920: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64   access.** to [d
c930: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c940: 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
c950: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73  ed statements] s
c960: 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70  o that the.** ap
c970: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65  plication is fre
c980: 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  e to use the sam
c990: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
c9a0: 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a  ection] or the.*
c9b0: 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  * same [prepared
c9c0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64   statement] in d
c9d0: 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73  ifferent threads
c9e0: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
c9f0: 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
ca00: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
ca10: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
ca20: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
ca30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
ca40: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
ca50: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
ca60: 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
ca70: 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72  e to set the Ser
ca80: 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
ca90: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
caa0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
cab0: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
cac0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
cad0: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
cae0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
caf0: 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e  G_SERIALIZED con
cb00: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
cb10: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  n.</dd>.**.** <d
cb20: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
cb30: 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
cb40: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
cb50: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
cb60: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
cb70: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
cb80: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
cb90: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
cba0: 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
cbb0: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
cbc0: 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
cbd0: 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
cbe0: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
cbf0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
cc00: 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
cc10: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
cc20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
cc30: 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
cc40: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
cc50: 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
cc60: 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
cc70: 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
cc80: 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
cc90: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
cca0: 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
ccb0: 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
ccc0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
ccd0: 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
cce0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
ccf0: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
cd00: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
cd10: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
cd20: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
cd30: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
cd40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
cd50: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
cd60: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
cd70: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
cd80: 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
cd90: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
cda0: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
cdb0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
cdc0: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
cdd0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cde0: 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
cdf0: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
ce00: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
ce10: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
ce20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ce30: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
ce40: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
ce50: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
ce60: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ce70: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
ce80: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
ce90: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
cea0: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
ceb0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
cec0: 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
ced0: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
cee0: 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
cef0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
cf00: 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65   int, interprete
cf10: 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65  d as a .** boole
cf20: 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
cf30: 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
cf40: 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20  e collection of 
cf50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
cf60: 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73  n .** statistics
cf70: 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20  . ^(When memory 
cf80: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
cf90: 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
cfa0: 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c  ed, the .** foll
cfb0: 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
cfc0: 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
cfd0: 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
cfe0: 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
cff0: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
d000: 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
d010: 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
d020: 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
d030: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
d040: 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
d050: 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c  limit()].**   <l
d060: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
d070: 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  us()].**   </ul>
d080: 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
d090: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
d0a0: 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
d0b0: 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
d0c0: 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
d0d0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
d0e0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
d0f0: 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
d100: 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
d110: 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
d120: 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
d130: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
d140: 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
d150: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
d160: 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
d170: 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
d180: 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
d190: 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
d1a0: 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
d1b0: 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
d1c0: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
d1d0: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
d1e0: 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70   arguments:  A p
d1f0: 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65  ointer an 8-byte
d200: 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  .** aligned memo
d210: 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77  ry buffer from w
d220: 68 69 63 68 20 74 68 65 20 73 63 72 61 63 68 20  hich the scrach 
d230: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
d240: 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
d250: 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
d260: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
d270: 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
d280: 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
d290: 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
d2a0: 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54  ocations (N).  T
d2b0: 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e  he sz.** argumen
d2c0: 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74  t must be a mult
d2d0: 69 70 6c 65 20 6f 66 20 31 36 2e 20 54 68 65 20  iple of 16. The 
d2e0: 73 7a 20 70 61 72 61 6d 65 74 65 72 20 73 68 6f  sz parameter sho
d2f0: 75 6c 64 20 62 65 20 61 20 66 65 77 20 62 79 74  uld be a few byt
d300: 65 73 0a 2a 2a 20 6c 61 72 67 65 72 20 74 68 61  es.** larger tha
d310: 6e 20 74 68 65 20 61 63 74 75 61 6c 20 73 63 72  n the actual scr
d320: 61 74 63 68 20 73 70 61 63 65 20 72 65 71 75 69  atch space requi
d330: 72 65 64 20 64 75 65 20 74 6f 20 69 6e 74 65 72  red due to inter
d340: 6e 61 6c 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a  nal overhead..**
d350: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
d360: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
d370: 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
d380: 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
d390: 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
d3a0: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
d3b0: 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
d3c0: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
d3d0: 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61  re than one scra
d3e0: 74 63 68 20 62 75 66 66 65 72 20 70 65 72 20 74  tch buffer per t
d3f0: 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20  hread.  So.** N 
d400: 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f  should be set to
d410: 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61   the expected ma
d420: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
d430: 74 68 72 65 61 64 73 2e 20 20 5e 53 51 4c 69 74  threads.  ^SQLit
d440: 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20  e will.** never 
d450: 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
d460: 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
d470: 20 6d 6f 72 65 20 74 68 61 6e 20 36 20 74 69 6d   more than 6 tim
d480: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  es the database.
d490: 2a 2a 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  ** page size. ^I
d4a0: 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
d4b0: 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 20  eeds additional 
d4c0: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
d4d0: 65 79 6f 6e 64 20 0a 2a 2a 20 77 68 61 74 20 69  eyond .** what i
d4e0: 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  s provided by th
d4f0: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
d500: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a   option, then .*
d510: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
d520: 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65  c()] will be use
d530: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
d540: 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f  memory needed.</
d550: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d560: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
d570: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
d580: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
d590: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
d5a0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
d5b0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
d5c0: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20   use for.** the 
d5d0: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
d5e0: 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
d5f0: 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65 20  ault page cache 
d600: 69 6d 70 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20  implemenation.  
d610: 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
d620: 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f  ration should no
d630: 74 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20  t be used if an 
d640: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
d650: 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
d660: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d670: 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
d680: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
d690: 47 5f 50 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e  G_PCACHE option.
d6a0: 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
d6b0: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
d6c0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
d6d0: 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
d6e0: 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
d6f0: 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
d700: 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
d710: 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
d720: 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
d730: 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
d740: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
d750: 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
d760: 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
d770: 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
d780: 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
d790: 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
d7a0: 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
d7b0: 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
d7c0: 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
d7d0: 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72  ^The page header
d7e0: 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
d7f0: 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
d800: 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
d810: 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
d820: 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
d830: 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
d840: 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
d850: 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c  * to make sz a l
d860: 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e  ittle too large.
d870: 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
d880: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
d890: 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
d8a0: 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
d8b0: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
d8c0: 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
d8d0: 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
d8e0: 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
d8f0: 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
d900: 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
d910: 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
d920: 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
d930: 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
d940: 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
d950: 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
d960: 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
d970: 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
d980: 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
d990: 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
d9a0: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
d9b0: 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
d9c0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
d9d0: 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
d9e0: 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
d9f0: 61 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6d 70  ace..** ^The imp
da00: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
da10: 74 20 75 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72  t use one or mor
da20: 65 20 6f 66 20 74 68 65 20 4e 20 62 75 66 66 65  e of the N buffe
da30: 72 73 20 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d  rs to hold .** m
da40: 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67  emory accounting
da50: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68   information. Th
da60: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
da70: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
da80: 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
da90: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
daa0: 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
dab0: 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
dac0: 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
dad0: 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
dae0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
daf0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
db00: 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
db10: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
db20: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
db30: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
db40: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t SQLite will us
db50: 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20  e.** for all of 
db60: 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
db70: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
db80: 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65  eds beyond those
db90: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72   provided.** for
dba0: 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
dbb0: 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20  IG_SCRATCH] and 
dbc0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
dbd0: 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68  AGECACHE]..** Th
dbe0: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
dbf0: 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79  guments: An 8-by
dc00: 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
dc10: 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
dc20: 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
dc30: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
dc40: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
dc50: 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
dc60: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
dc70: 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
dc80: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
dc90: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
dca0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
dcb0: 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
dcc0: 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
dcd0: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
dce0: 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
dcf0: 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
dd00: 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
dd10: 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
dd20: 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
dd30: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
dd40: 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
dd50: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
dd60: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
dd70: 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
dd80: 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
dd90: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  r.** [SQLITE_ENA
dda0: 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65  BLE_MEMSYS5] are
ddb0: 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74   defined, then t
ddc0: 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d  he alternative m
ddd0: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
dde0: 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f  or is engaged to
ddf0: 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53   handle all of S
de00: 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c  QLites memory al
de10: 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a  location needs..
de20: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69  ** The first poi
de30: 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
de40: 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62   pointer) must b
de50: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
de60: 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61  8-byte.** bounda
de70: 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
de80: 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
de90: 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  ite will be unde
dea0: 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
deb0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
dec0: 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
ded0: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
dee0: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
def0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
df00: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
df10: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
df20: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
df30: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
df40: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
df50: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
df60: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
df70: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
df80: 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
df90: 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a  e used in place.
dfa0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ** the mutex rou
dfb0: 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
dfc0: 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
dfd0: 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
dfe0: 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65   of the.** conte
dff0: 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
e000: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
e010: 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
e020: 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
e030: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
e040: 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
e050: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
e060: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
e070: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
e080: 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
e090: 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
e0a0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
e0b0: 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
e0c0: 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
e0d0: 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
e0e0: 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
e0f0: 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
e100: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
e110: 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
e120: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
e130: 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
e140: 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
e150: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
e160: 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
e170: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
e180: 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
e190: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
e1a0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
e1b0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
e1c0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
e1d0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
e1e0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
e1f0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
e200: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
e210: 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
e220: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
e230: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
e240: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
e250: 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
e260: 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
e270: 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
e280: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
e290: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
e2a0: 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
e2b0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
e2c0: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
e2d0: 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
e2e0: 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
e2f0: 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
e300: 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
e310: 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
e320: 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
e330: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
e340: 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
e350: 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
e360: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
e370: 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
e380: 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
e390: 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
e3a0: 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
e3b0: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
e3c0: 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
e3d0: 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
e3e0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
e3f0: 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
e400: 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
e410: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
e420: 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
e430: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
e440: 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  R].</dd>.**.** <
e450: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
e460: 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
e470: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
e480: 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
e490: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
e4a0: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66  etermine the def
e4b0: 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  ault.** memory a
e4c0: 6c 6c 6f 63 61 74 69 6f 6e 20 6c 6f 6f 6b 61 73  llocation lookas
e4d0: 69 64 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ide optimization
e4e0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
e4f0: 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
e500: 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
e510: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
e520: 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
e530: 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
e540: 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
e550: 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
e560: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e570: 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
e580: 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
e590: 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
e5a0: 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
e5b0: 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
e5c0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
e5d0: 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
e5e0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
e5f0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
e600: 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
e610: 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
e620: 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
e630: 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
e640: 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ^ </dd>.**.** <d
e650: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
e660: 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
e670: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
e680: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
e690: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
e6a0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
e6b0: 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ** an [sqlite3_p
e6c0: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f  cache_methods] o
e6d0: 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
e6e0: 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68  ect specifies th
e6f0: 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  e interface.** t
e700: 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
e710: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
e720: 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65  tion.)^  ^SQLite
e730: 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
e740: 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
e750: 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
e760: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
e770: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
e780: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
e790: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
e7a0: 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
e7b0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
e7c0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
e7d0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
e7e0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
e7f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
e800: 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
e810: 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
e820: 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
e830: 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
e840: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e850: 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
e860: 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
e870: 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
e880: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
e890: 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
e8a0: 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
e8b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
e8c0: 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
e8d0: 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
e8e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
e8f0: 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
e900: 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
e910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
e920: 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
e930: 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
e940: 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
e950: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
e960: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
e970: 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
e980: 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
e990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
e9a0: 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
e9b0: 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
e9c0: 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
e9d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e9e0: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
e9f0: 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
ea00: 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
ea10: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
ea20: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
ea30: 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
ea40: 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
ea50: 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
ea60: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
ea70: 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
ea80: 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
ea90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
eaa0: 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
eab0: 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
eac0: 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
ead0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
eae0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
eaf0: 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
eb00: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
eb10: 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
eb20: 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
eb30: 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
eb40: 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
eb50: 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
eb60: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
eb70: 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
eb80: 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
eb90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
eba0: 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
ebb0: 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65     14  /* sqlite
ebc0: 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
ebd0: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
ebe0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
ebf0: 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73  ACHE    15  /* s
ec00: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
ec10: 74 68 6f 64 73 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  thods* */../*.**
ec20: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
ec30: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
ec40: 20 7b 48 31 30 31 37 30 7d 20 3c 53 32 30 30 30   {H10170} <S2000
ec50: 30 3e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  0>.** EXPERIMENT
ec60: 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  AL.**.** These c
ec70: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
ec80: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
ec90: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
eca0: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
ecb0: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
ecc0: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
ecd0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
ece0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
ecf0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
ed00: 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
ed10: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
ed20: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
ed30: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
ed40: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
ed50: 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
ed60: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
ed70: 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
ed80: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
ed90: 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
eda0: 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
edb0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62  from [sqlite3_db
edc0: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
edd0: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
ede0: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
edf0: 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
ee00: 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
ee10: 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
ee20: 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
ee30: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
ee40: 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
ee50: 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
ee60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
ee70: 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
ee80: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
ee90: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
eea0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
eeb0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
eec0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
eed0: 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  hree additional 
eee0: 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
eef0: 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a  etermine the .**
ef00: 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
ef10: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f  ry allocator] co
ef20: 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
ef30: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
ef40: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54  nnection]..** ^T
ef50: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
ef60: 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61 72  t (the third par
ef70: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
ef80: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
ef90: 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
efa0: 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66  to an memory buf
efb0: 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
efc0: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
efd0: 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
efe0: 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
eff0: 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
f000: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
f010: 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
f020: 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
f030: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
f040: 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
f050: 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
f060: 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
f070: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
f080: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
f090: 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
f0a0: 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
f0b0: 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
f0c0: 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
f0d0: 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
f0e0: 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
f0f0: 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
f100: 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
f110: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
f120: 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
f130: 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
f140: 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
f150: 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
f160: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
f170: 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
f180: 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
f190: 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
f1a0: 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
f1b0: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
f1c0: 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
f1d0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
f1e0: 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
f1f0: 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
f200: 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
f210: 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
f220: 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a 2a 20 6d  ext smaller.** m
f230: 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 53  ultiple of 8.  S
f240: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
f250: 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
f260: 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  E]</dd>.**.** </
f270: 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
f280: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
f290: 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 30 30 31  OOKASIDE    1001
f2a0: 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
f2b0: 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt */.../*.** CA
f2c0: 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
f2d0: 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
f2e0: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
f2f0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
f300: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
f310: 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
f320: 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
f330: 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
f340: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
f350: 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
f360: 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
f370: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
f380: 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
f390: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
f3a0: 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
f3b0: 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
f3c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
f3d0: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
f3e0: 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
f3f0: 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
f400: 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
f410: 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
f420: 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
f430: 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
f440: 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
f450: 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
f460: 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
f470: 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
f480: 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
f490: 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
f4a0: 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
f4b0: 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
f4c0: 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
f4d0: 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
f4e0: 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
f4f0: 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
f500: 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
f510: 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
f520: 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
f530: 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
f540: 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
f550: 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
f560: 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
f570: 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
f580: 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
f590: 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
f5a0: 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
f5b0: 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
f5c0: 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
f5d0: 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
f5e0: 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
f5f0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
f600: 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
f610: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
f620: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
f630: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20  gument.  ^If no 
f640: 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
f650: 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
f660: 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
f670: 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
f680: 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
f690: 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
f6a0: 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
f6b0: 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
f6c0: 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
f6d0: 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
f6e0: 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
f6f0: 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
f700: 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
f710: 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
f720: 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
f730: 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
f740: 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
f750: 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
f760: 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
f770: 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
f780: 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
f790: 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
f7a0: 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
f7b0: 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20   fired.)^.**.** 
f7c0: 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
f7d0: 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
f7e0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
f7f0: 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
f800: 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
f810: 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
f820: 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
f830: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
f840: 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
f850: 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
f860: 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
f870: 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
f880: 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
f890: 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
f8a0: 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
f8b0: 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
f8c0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
f8d0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
f8e0: 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
f8f0: 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
f900: 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
f910: 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
f920: 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
f930: 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
f940: 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
f950: 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
f960: 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
f970: 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
f980: 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
f990: 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
f9a0: 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
f9b0: 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
f9c0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
f9d0: 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
f9e0: 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
f9f0: 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
fa00: 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
fa10: 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
fa20: 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
fa30: 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
fa40: 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
fa50: 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
fa60: 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
fa70: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
fa80: 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
fa90: 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
faa0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
fab0: 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
fac0: 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
fad0: 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
fae0: 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
faf0: 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
fb00: 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
fb10: 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
fb20: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
fb30: 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
fb40: 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
fb50: 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
fb60: 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
fb70: 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
fb80: 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
fb90: 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
fba0: 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
fbb0: 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
fbc0: 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
fbd0: 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
fbe0: 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
fbf0: 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
fc00: 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
fc10: 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
fc20: 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
fc30: 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
fc40: 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
fc50: 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
fc60: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
fc70: 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
fc80: 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
fc90: 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
fca0: 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
fcb0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
fcc0: 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
fcd0: 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
fce0: 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
fcf0: 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
fd00: 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
fd10: 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
fd20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
fd30: 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
fd40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
fd50: 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
fd60: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
fd70: 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65  ** ^(Only change
fd80: 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
fd90: 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
fda0: 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
fdb0: 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
fdc0: 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
fdd0: 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
fde0: 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
fdf0: 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
fe00: 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65  riggers or [fore
fe10: 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
fe20: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
fe30: 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  .)^ Use the.** [
fe40: 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
fe50: 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
fe60: 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
fe70: 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
fe80: 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
fe90: 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
fea0: 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
feb0: 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
fec0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68  tions..**.** ^Ch
fed0: 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
fee0: 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74  that are simulat
fef0: 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41  ed by an [INSTEA
ff00: 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a  D OF trigger].**
ff10: 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
ff20: 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62  .  Only real tab
ff30: 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  le changes are c
ff40: 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ounted..**.** ^(
ff50: 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
ff60: 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
ff70: 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
ff80: 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
ff90: 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
ffa0: 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
ffb0: 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
ffc0: 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
ffd0: 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
ffe0: 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
fff0: 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
10000 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
10010 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
10020 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
10030 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
10040 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
10050 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
10060 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
10070 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e  t row changes.)^
10080 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
10090 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
100a0 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
100b0 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
100c0 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
100d0 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
100e0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
100f0 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
10100 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
10110 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
10120 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
10130 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
10140 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
10150 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
10160 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
10170 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
10180 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
10190 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
101a0 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
101b0 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
101c0 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
101d0 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
101e0 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
101f0 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
10200 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
10210 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  n..**.** ^Callin
10220 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
10230 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
10240 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
10250 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
10260 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
10270 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
10280 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
10290 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
102a0 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
102b0 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
102c0 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
102d0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
102e0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
102f0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
10300 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
10310 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
10320 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
10330 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
10340 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
10350 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
10360 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
10370 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
10380 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
10390 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
103a0 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
103b0 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
103c0 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74  op level.  ^(Wit
103d0 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
103e0 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
103f0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
10400 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
10410 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
10420 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
10430 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
10440 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
10450 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
10460 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
10470 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
10480 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
10490 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
104a0 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
104b0 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
104c0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
104d0 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
104e0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
104f0 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
10500 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
10510 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a   own context.)^.
10520 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
10530 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
10540 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
10550 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
10560 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
10570 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
10580 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
10590 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
105a0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
105b0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
105c0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
105d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
105e0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
105f0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
10600 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
10610 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
10620 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
10630 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
10640 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
10650 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
10660 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
10670 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
10680 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
10690 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
106a0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
106b0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
106c0 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
106d0 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
106e0 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
106f0 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
10700 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
10710 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
10720 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
10730 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
10740 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
10750 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
10760 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
10770 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
10780 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
10790 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
107a0 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
107b0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
107c0 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
107d0 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
107e0 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
107f0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
10800 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
10810 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
10820 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
10830 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
10840 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
10850 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
10860 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
10870 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
10880 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
10890 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
108a0 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
108b0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
108c0 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
108d0 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
108e0 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
108f0 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
10900 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
10910 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
10920 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
10930 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
10940 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
10950 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
10960 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
10970 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
10980 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
10990 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
109a0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
109b0 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
109c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
109d0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
109e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
109f0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
10a00 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
10a10 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
10a20 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
10a30 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
10a40 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
10a50 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
10a60 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
10a70 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
10a80 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
10a90 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
10aa0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10ab0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
10ac0 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
10ad0 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
10ae0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
10af0 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
10b00 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
10b10 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
10b20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
10b30 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
10b40 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
10b50 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
10b60 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
10b70 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
10b80 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
10b90 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
10ba0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
10bb0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
10bc0 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
10bd0 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
10be0 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
10bf0 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
10c00 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
10c10 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
10c20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
10c30 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
10c40 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
10c50 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
10c60 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
10c70 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
10c80 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
10c90 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
10ca0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
10cb0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
10cc0 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
10cd0 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
10ce0 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
10cf0 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
10d00 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
10d10 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
10d20 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
10d30 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
10d40 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
10d50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
10d60 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
10d70 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
10d80 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
10d90 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
10da0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
10db0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
10dc0 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
10dd0 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
10de0 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
10df0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
10e00 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
10e10 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
10e20 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
10e30 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
10e40 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
10e50 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
10e60 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
10e70 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
10e80 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
10e90 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
10ea0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
10eb0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
10ec0 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
10ed0 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
10ee0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
10ef0 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
10f00 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
10f10 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
10f20 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
10f30 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
10f40 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
10f50 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
10f60 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  lly..**.** ^(The
10f70 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
10f80 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
10f90 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
10fa0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
10fb0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
10fc0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
10fd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
10fe0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 41 6e 79 20   complete.  Any 
10ff0 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
11000 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
11010 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
11020 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
11030 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
11040 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
11050 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
11060 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
11070 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
11080 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
11090 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
110a0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
110b0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
110c0 6c 2e 20 20 4e 65 77 20 53 51 4c 20 73 74 61 74  l.  New SQL stat
110d0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
110e0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
110f0 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
11100 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
11110 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
11120 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
11130 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
11140 65 72 72 75 70 74 28 29 2e 29 5e 0a 2a 2a 20 5e  errupt().)^.** ^
11150 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
11160 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
11170 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
11180 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
11190 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
111a0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
111b0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
111c0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
111d0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
111e0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
111f0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
11200 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
11210 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
11220 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
11230 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
11240 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
11250 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
11260 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
11270 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
11280 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
11290 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
112a0 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
112b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
112c0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
112d0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
112e0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
112f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
11300 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
11310 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
11320 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
11330 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
11340 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
11350 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
11360 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
11370 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
11380 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
11390 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
113a0 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
113b0 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
113c0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
113d0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
113e0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
113f0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
11400 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
11410 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
11420 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
11430 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
11440 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
11450 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
11460 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
11470 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
11480 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
11490 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
114a0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
114b0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
114c0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
114d0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
114e0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
114f0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
11500 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
11510 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
11520 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
11530 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
11540 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
11550 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
11560 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
11570 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
11580 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
11590 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
115a0 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
115b0 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
115c0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
115d0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
115e0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
115f0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
11600 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
11610 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
11620 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
11630 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
11640 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
11650 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
11660 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
11670 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
11680 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
11690 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
116a0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
116b0 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
116c0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
116d0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
116e0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
116f0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
11700 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
11710 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11720 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
11730 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
11740 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
11750 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
11760 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
11770 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
11780 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
11790 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
117a0 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
117b0 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
117c0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
117d0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
117e0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
117f0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
11800 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
11810 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
11820 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
11830 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
11840 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
11850 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
11860 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
11870 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
11880 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
11890 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
118a0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
118b0 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
118c0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
118d0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
118e0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
118f0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
11900 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
11910 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
11920 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
11930 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
11940 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
11950 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
11960 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
11970 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
11980 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
11990 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
119a0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
119b0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
119c0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
119d0 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
119e0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
119f0 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
11a00 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
11a10 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
11a20 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
11a30 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  locked..**.** ^I
11a40 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
11a50 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
11a60 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
11a70 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
11a80 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
11a90 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
11aa0 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
11ab0 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
11ac0 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
11ad0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
11ae0 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
11af0 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
11b00 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
11b10 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
11b20 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
11b30 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
11b40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
11b50 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
11b60 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
11b70 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
11b80 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
11b90 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
11ba0 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
11bb0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
11bc0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
11bd0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
11be0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
11bf0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
11c00 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
11c10 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
11c20 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
11c30 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
11c40 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
11c50 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
11c60 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
11c70 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
11c80 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
11c90 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
11ca0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
11cb0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
11cc0 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
11cd0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
11ce0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
11cf0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
11d00 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
11d10 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
11d20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
11d30 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
11d40 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
11d50 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
11d60 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
11d70 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
11d80 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
11d90 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
11da0 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
11db0 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
11dc0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
11dd0 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
11de0 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
11df0 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
11e00 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
11e10 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
11e20 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
11e30 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
11e40 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
11e50 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
11e60 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
11e70 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
11e80 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
11e90 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
11ea0 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
11eb0 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
11ec0 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
11ed0 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
11ee0 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
11ef0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
11f00 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
11f10 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
11f20 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
11f30 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
11f40 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
11f50 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
11f60 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
11f70 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
11f80 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
11f90 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
11fa0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
11fb0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
11fc0 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
11fd0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
11fe0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
11ff0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
12000 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
12010 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
12020 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
12030 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
12040 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
12050 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
12060 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
12070 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
12080 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
12090 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
120a0 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
120b0 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
120c0 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
120d0 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
120e0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
120f0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
12100 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
12110 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
12120 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
12130 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
12140 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
12150 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
12160 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
12170 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
12180 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
12190 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
121a0 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
121b0 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
121c0 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
121d0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
121e0 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
121f0 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
12200 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
12210 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
12220 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
12230 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
12240 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
12250 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
12260 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
12270 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
12280 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
12290 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
122a0 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
122b0 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49  .** readers.  ^I
122c0 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
122d0 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
122e0 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
122f0 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
12300 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
12310 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
12320 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
12330 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
12340 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
12350 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
12360 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
12370 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
12380 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
12390 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
123a0 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63  .  ^This error c
123b0 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
123c0 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
123d0 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
123e0 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
123f0 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
12400 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
12410 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
12420 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
12430 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
12440 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
12450 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
12460 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
12470 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
12480 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
12490 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
124a0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
124b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
124c0 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
124d0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
124e0 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
124f0 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
12500 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
12510 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
12520 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
12530 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
12540 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
12550 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c  imeout()].** wil
12560 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
12570 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e  ear the busy han
12580 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
12590 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
125a0 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
125b0 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
125c0 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
125d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
125e0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
125f0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
12600 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
12610 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
12620 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
12630 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
12640 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
12650 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
12660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12670 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
12680 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
12690 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
126a0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
126b0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
126c0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
126d0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
126e0 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
126f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
12700 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
12710 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
12720 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
12730 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
12740 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
12750 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
12760 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
12770 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
12780 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
12790 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
127a0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
127b0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
127c0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
127d0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
127e0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
127f0 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
12800 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
12810 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
12820 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
12830 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
12840 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
12850 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
12860 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
12870 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
12880 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
12890 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
128a0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
128b0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
128c0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
128d0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
128e0 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
128f0 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
12900 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
12910 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
12920 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
12930 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
12940 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
12950 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12960 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
12970 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
12980 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
12990 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
129a0 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
129b0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
129c0 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
129d0 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
129e0 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
129f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
12a00 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e  cleared.)^.*/.in
12a10 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
12a20 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
12a30 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
12a40 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
12a50 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
12a60 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
12a70 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ies.**.** Defini
12a80 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
12a90 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
12aa0 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
12ab0 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
12ac0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
12ad0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
12ae0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
12af0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
12b00 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
12b10 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
12b20 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
12b30 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
12b40 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
12b50 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
12b60 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
12b70 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
12b80 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
12b90 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
12ba0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
12bb0 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
12bc0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
12bd0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
12be0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
12bf0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
12c00 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
12c10 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
12c20 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
12c30 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
12c40 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
12c50 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
12c60 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
12c70 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
12c80 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
12c90 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
12ca0 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
12cb0 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
12cc0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
12cd0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
12ce0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
12cf0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
12d00 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
12d10 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
12d20 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
12d30 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
12d40 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
12d50 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
12d60 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
12d70 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
12d80 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
12d90 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
12da0 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
12db0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
12dc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
12dd0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
12de0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
12df0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
12e00 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
12e10 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
12e20 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
12e30 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
12e40 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
12e50 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
12e60 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
12e70 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
12e80 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
12e90 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
12ea0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 61 6e  ()]..**.** As an
12eb0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
12ec0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
12ed0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
12ee0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
12ef0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
12f00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
12f10 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
12f20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
12f30 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
12f40 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
12f50 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
12f60 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
12f70 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
12f80 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
12f90 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
12fa0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
12fb0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
12fc0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
12fd0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
12fe0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
12ff0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
13000 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
13010 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
13020 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
13030 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
13040 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
13050 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
13060 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
13070 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
13080 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
13090 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
130a0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
130b0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
130c0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
130d0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
130e0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
130f0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
13100 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
13110 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
13120 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
13130 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
13140 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
13150 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
13160 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
13170 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
13180 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
13190 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
131a0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
131b0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
131c0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
131d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
131e0 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
131f0 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
13200 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
13210 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
13220 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
13230 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
13240 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
13250 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
13260 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
13270 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
13280 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
13290 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
132a0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
132b0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
132c0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
132d0 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
132e0 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
132f0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
13300 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 73  table(),.** it s
13310 68 6f 75 6c 64 20 70 61 73 73 20 74 68 65 20 72  hould pass the r
13320 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
13330 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
13340 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
13350 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
13360 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
13370 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
13380 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
13390 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
133a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
133b0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
133c0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
133d0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
133e0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
133f0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
13400 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
13410 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
13420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
13430 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
13440 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
13450 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
13460 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
13470 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
13480 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
13490 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
134a0 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
134b0 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
134c0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
134d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
134e0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
134f0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
13500 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
13510 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
13520 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
13530 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
13540 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
13550 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
13560 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
13570 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
13580 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
13590 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
135a0 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
135b0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
135c0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
135d0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
135e0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
135f0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
13600 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
13610 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
13620 33 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e 0a 2a  3_errmsg()].)^.*
13630 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  /.int sqlite3_ge
13640 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
13650 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
13660 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
13670 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
13680 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
13690 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
136a0 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
136b0 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
136c0 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
136d0 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
136e0 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
136f0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
13700 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
13710 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
13720 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
13730 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
13740 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
13750 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
13760 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
13770 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
13780 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
13790 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73  ere */.);.void s
137a0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
137b0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
137c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
137d0 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
137e0 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
137f0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
13800 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
13810 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
13820 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
13830 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
13840 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
13850 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
13860 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
13870 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
13880 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
13890 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
138a0 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
138b0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
138c0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
138d0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
138e0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
138f0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
13900 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
13910 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
13920 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
13930 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
13940 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
13950 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
13960 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
13970 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
13980 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
13990 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
139a0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
139b0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
139c0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71 6c 69  .**.** ^(In sqli
139d0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
139e0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
139f0 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
13a00 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
13a10 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
13a20 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
13a30 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
13a40 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
13a50 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
13a60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
13a70 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
13a80 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
13a90 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
13aa0 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
13ab0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
13ac0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
13ad0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
13ae0 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
13af0 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
13b00 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
13b10 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
13b20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
13b30 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
13b40 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
13b50 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
13b60 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
13b70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
13b80 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
13b90 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
13ba0 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
13bb0 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
13bc0 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
13bd0 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
13be0 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
13bf0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
13c00 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
13c10 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
13c20 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
13c30 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
13c40 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
13c50 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
13c60 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
13c70 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
13c80 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
13c90 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
13ca0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
13cb0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
13cc0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
13cd0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
13ce0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
13cf0 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
13d00 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
13d10 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
13d20 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
13d30 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
13d40 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
13d50 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
13d60 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
13d70 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
13d80 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
13d90 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
13da0 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
13db0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
13dc0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
13dd0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
13de0 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  rs..**.** These 
13df0 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
13e00 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
13e10 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
13e20 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
13e30 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
13e40 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
13e50 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
13e60 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
13e70 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
13e80 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
13e90 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
13ea0 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
13eb0 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61  re "%q", "%Q", a
13ec0 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e  nd "%z" options.
13ed0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20  .**.** ^(The %q 
13ee0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
13ef0 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20  e %s in that it 
13f00 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75  substitutes a nu
13f10 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ll-terminated.**
13f20 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
13f30 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
13f40 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
13f50 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
13f60 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
13f70 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
13f80 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
13f90 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
13fa0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
13fb0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
13fc0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
13fd0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
13fe0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
13ff0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
14000 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
14010 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
14020 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
14030 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
14040 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
14050 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
14060 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
14070 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
14080 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
14090 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
140a0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
140b0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
140c0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
140d0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
140e0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
140f0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
14100 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
14110 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
14120 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
14130 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
14140 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
14150 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
14160 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
14170 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
14180 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
14190 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
141a0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
141b0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
141c0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
141d0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
141e0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
141f0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
14200 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
14210 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
14220 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
14230 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
14240 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
14250 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
14260 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
14270 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14280 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
14290 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
142a0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
142b0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
142c0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
142d0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
142e0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
142f0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
14300 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
14310 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
14320 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
14330 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
14340 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
14350 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
14360 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
14370 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
14380 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
14390 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
143a0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
143b0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
143c0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
143d0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
143e0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
143f0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
14400 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
14410 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
14420 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
14430 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
14440 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
14450 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
14460 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
14470 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
14480 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
14490 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
144a0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
144b0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
144c0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
144d0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
144e0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
144f0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
14500 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
14510 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
14520 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
14530 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
14540 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
14550 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
14560 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
14570 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
14580 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
14590 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
145a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
145b0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
145c0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
145d0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
145e0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
145f0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
14600 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
14610 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
14620 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
14630 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
14640 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
14650 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
14660 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
14670 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
14680 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
14690 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
146a0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
146b0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
146c0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
146d0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
146e0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
146f0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
14700 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
14710 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
14720 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
14730 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
14740 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
14750 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
14760 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
14770 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
14780 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
14790 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
147a0 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
147b0 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
147c0 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
147d0 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
147e0 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
147f0 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
14800 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14810 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
14820 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
14830 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
14840 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
14850 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
14860 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
14870 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
14880 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
14890 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
148a0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
148b0 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
148c0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
148d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
148e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
148f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
14900 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
14910 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
14920 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
14930 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
14940 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
14950 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14960 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
14970 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
14980 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
14990 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
149a0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
149b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
149c0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
149d0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
149e0 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
149f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14a00 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
14a10 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
14a20 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
14a30 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
14a40 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
14a50 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
14a60 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
14a70 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
14a80 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
14a90 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
14aa0 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
14ab0 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
14ac0 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
14ad0 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
14ae0 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
14af0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
14b00 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
14b10 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
14b20 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
14b30 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
14b40 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
14b50 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
14b60 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
14b70 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
14b80 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
14b90 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
14ba0 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
14bb0 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
14bc0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
14bd0 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
14be0 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
14bf0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
14c00 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
14c10 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
14c20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
14c30 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
14c40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
14c50 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
14c60 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
14c70 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
14c80 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
14c90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
14ca0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
14cb0 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
14cc0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
14cd0 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
14ce0 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
14cf0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
14d00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
14d10 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
14d20 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
14d30 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
14d40 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
14d50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14d60 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
14d70 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
14d80 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
14d90 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14da0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
14db0 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
14dc0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
14dd0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
14de0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
14df0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
14e00 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
14e10 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
14e20 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
14e30 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
14e40 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
14e50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
14e60 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
14e70 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
14e80 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
14e90 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
14ea0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
14eb0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
14ec0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
14ed0 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
14ee0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
14ef0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
14f00 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
14f10 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
14f20 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
14f30 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
14f40 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
14f50 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
14f60 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
14f70 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
14f80 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
14f90 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
14fa0 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
14fb0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
14fc0 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
14fd0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
14fe0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
14ff0 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
15000 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
15010 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
15020 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
15030 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
15040 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
15050 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
15060 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15070 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
15080 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
15090 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
150a0 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
150b0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
150c0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
150d0 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
150e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
150f0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
15100 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
15110 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
15120 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  ary..**.** In SQ
15130 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
15140 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
15150 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
15160 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
15170 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
15180 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
15190 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
151a0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
151b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
151c0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
151d0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
151e0 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
151f0 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
15200 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
15210 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
15220 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
15230 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  e used..**.** Th
15240 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
15250 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
15260 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ls.** the system
15270 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
15280 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
15290 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
152a0 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
152b0 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
152c0 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
152d0 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
152e0 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
152f0 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
15300 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
15310 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
15320 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
15330 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
15340 6f 72 73 20 61 72 65 20 64 65 74 65 63 74 65 64  ors are detected
15350 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 61 72  , but.** they ar
15360 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
15370 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
15380 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
15390 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
153a0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
153b0 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
153c0 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
153d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
153e0 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
153f0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
15400 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
15410 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
15420 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
15430 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
15440 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
15450 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
15460 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
15470 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
15480 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
15490 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
154a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
154b0 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
154c0 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
154d0 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
154e0 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
154f0 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
15500 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
15510 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
15520 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
15530 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  c()]..*/.void *s
15540 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e  qlite3_malloc(in
15550 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  t);.void *sqlite
15560 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
15570 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
15580 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
15590 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
155a0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
155b0 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
155c0 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
155d0 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
155e0 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
155f0 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
15600 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
15610 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
15620 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
15630 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
15640 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
15650 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
15660 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
15670 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
15680 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
15690 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
156a0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
156b0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
156c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
156d0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
156e0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
156f0 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
15700 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
15710 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
15720 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
15730 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
15740 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
15750 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
15760 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
15770 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
15780 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
15790 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
157a0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
157b0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
157c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
157d0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
157e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
157f0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
15800 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
15810 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
15820 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
15830 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
15840 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
15850 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
15860 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
15870 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
15880 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
15890 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
158a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
158b0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
158c0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
158d0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
158e0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
158f0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
15900 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
15910 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
15920 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
15930 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
15940 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
15950 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
15960 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
15970 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
15980 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
15990 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
159a0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
159b0 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
159c0 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
159d0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
159e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
159f0 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
15a00 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
15a10 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
15a20 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
15a30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
15a40 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
15a50 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
15a60 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
15a70 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
15a80 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
15a90 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
15aa0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
15ab0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
15ac0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
15ad0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
15ae0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
15af0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
15b00 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
15b10 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
15b20 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
15b30 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
15b40 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
15b50 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
15b60 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
15b70 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
15b80 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
15b90 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
15ba0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
15bb0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
15bc0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
15bd0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
15be0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
15bf0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
15c00 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
15c10 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
15c20 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
15c30 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
15c40 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74   is invoked (eit
15c50 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f  her internally o
15c60 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c  r by.** the appl
15c70 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e  ication) the PRN
15c80 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
15c90 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
15ca0 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68  ained.** from th
15cb0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
15cc0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
15cd0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
15ce0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e  ] object..** ^On
15cf0 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
15d00 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
15d10 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
15d20 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
15d30 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
15d40 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
15d50 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
15d60 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
15d70 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
15d80 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
15d90 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c  andomness(int N,
15da0 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a   void *P);../*.*
15db0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
15dc0 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69  ile-Time Authori
15dd0 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  zation Callbacks
15de0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
15df0 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
15e00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
15e10 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74  back with a part
15e20 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
15e30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c  ase connection],
15e40 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65   supplied in the
15e50 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
15e60 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69  .** ^The authori
15e70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
15e80 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73  invoked as SQL s
15e90 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65  tatements are be
15ea0 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  ing compiled.** 
15eb0 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  by [sqlite3_prep
15ec0 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
15ed0 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f  riants [sqlite3_
15ee0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a  prepare_v2()],.*
15ef0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
15f00 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c  re16()] and [sql
15f10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
15f20 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f  2()].  ^At vario
15f30 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72  us.** points dur
15f40 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74  ing the compilat
15f50 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20  ion process, as 
15f60 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63  logic is being c
15f70 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72  reated.** to per
15f80 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74  form various act
15f90 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72  ions, the author
15fa0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
15fb0 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73   invoked to.** s
15fc0 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69  ee if those acti
15fd0 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e  ons are allowed.
15fe0 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65    ^The authorize
15ff0 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  r callback shoul
16000 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
16010 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77  ITE_OK] to allow
16020 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51   the action, [SQ
16030 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20  LITE_IGNORE] to 
16040 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20  disallow the.** 
16050 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20  specific action 
16060 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51  but allow the SQ
16070 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63  L statement to c
16080 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a  ontinue to be.**
16090 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53   compiled, or [S
160a0 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63  QLITE_DENY] to c
160b0 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20  ause the entire 
160c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
160d0 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20   be.** rejected 
160e0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
160f0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ^If the authoriz
16100 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  er callback retu
16110 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65  rns.** any value
16120 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
16130 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51  ITE_IGNORE], [SQ
16140 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51  LITE_OK], or [SQ
16150 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68  LITE_DENY].** th
16160 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  en the [sqlite3_
16170 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
16180 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
16190 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a   that triggered.
161a0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
161b0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
161c0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
161d0 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  e..**.** When th
161e0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
161f0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20  ns [SQLITE_OK], 
16200 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f  that means the o
16210 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75  peration.** requ
16220 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57  ested is ok.  ^W
16230 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
16240 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
16250 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b  _DENY], the.** [
16260 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
16270 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
16280 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
16290 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61  iggered the.** a
162a0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
162b0 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
162c0 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69  r message explai
162d0 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63  ning that.** acc
162e0 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a  ess is denied. .
162f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
16300 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
16310 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
16320 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
16330 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  of the third.** 
16340 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16350 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
16360 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66  horizer() interf
16370 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ace. ^The second
16380 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
16390 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
163a0 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c   an integer [SQL
163b0 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f  ITE_COPY | actio
163c0 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65  n code] that spe
163d0 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61  cifies.** the pa
163e0 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20  rticular action 
163f0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
16400 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72  . ^The third thr
16410 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d  ough sixth param
16420 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20  eters.** to the 
16430 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72  callback are zer
16440 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
16450 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69  ings that contai
16460 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  n additional.** 
16470 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68  details about th
16480 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  e action to be a
16490 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a  uthorized..**.**
164a0 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
164b0 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
164c0 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65  READ].** and the
164d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
164e0 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  s [SQLITE_IGNORE
164f0 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70  ] then the.** [p
16500 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
16510 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  t] statement is 
16520 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73  constructed to s
16530 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e  ubstitute.** a N
16540 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61  ULL value in pla
16550 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20  ce of the table 
16560 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c  column that woul
16570 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72  d have.** been r
16580 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f  ead if [SQLITE_O
16590 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75  K] had been retu
165a0 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49  rned.  The [SQLI
165b0 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65  TE_IGNORE].** re
165c0 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64  turn can be used
165d0 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72   to deny an untr
165e0 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73  usted user acces
165f0 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a  s to individual.
16600 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20  ** columns of a 
16610 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68  table..** ^If th
16620 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
16630 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d   [SQLITE_DELETE]
16640 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
16650 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  k returns.** [SQ
16660 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
16670 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f  n the [DELETE] o
16680 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64  peration proceed
16690 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72  s but the.** [tr
166a0 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74  uncate optimizat
166b0 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64  ion] is disabled
166c0 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72   and all rows ar
166d0 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69  e deleted indivi
166e0 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e  dually..**.** An
166f0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75   authorizer is u
16700 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  sed when [sqlite
16710 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
16720 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74  aring].** SQL st
16730 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e  atements from an
16740 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
16750 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  e, to ensure tha
16760 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  t the SQL statem
16770 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74  ents.** do not t
16780 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74  ry to access dat
16790 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61  a they are not a
167a0 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f  llowed to see, o
167b0 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  r that they do n
167c0 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65  ot.** try to exe
167d0 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73  cute malicious s
167e0 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64  tatements that d
167f0 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61  amage the databa
16800 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d  se.  For.** exam
16810 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
16820 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20  ion may allow a 
16830 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72  user to enter ar
16840 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71  bitrary.** SQL q
16850 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75  ueries for evalu
16860 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62  ation by a datab
16870 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70  ase.  But the ap
16880 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a  plication does.*
16890 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75  * not want the u
168a0 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74  ser to be able t
168b0 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79  o make arbitrary
168c0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a   changes to the.
168d0 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e  ** database.  An
168e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c   authorizer coul
168f0 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e  d then be put in
16900 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65   place while the
16910 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64  .** user-entered
16920 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73   SQL is being [s
16930 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
16940 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a   prepared] that.
16950 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65  ** disallows eve
16960 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b  rything except [
16970 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
16980 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ts..**.** Applic
16990 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64  ations that need
169a0 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20   to process SQL 
169b0 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73  from untrusted s
169c0 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20  ources.** might 
169d0 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f  also consider lo
169e0 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20  wering resource 
169f0 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71  limits using [sq
16a00 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
16a10 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64  * and limiting d
16a20 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69  atabase size usi
16a30 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65  ng the [max_page
16a40 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
16a50 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20  .** in addition 
16a60 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68  to using an auth
16a70 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  orizer..**.** ^(
16a80 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75  Only a single au
16a90 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20  thorizer can be 
16aa0 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61  in place on a da
16ab0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16ac0 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20  n.** at a time. 
16ad0 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71   Each call to sq
16ae0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
16af0 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74  izer overrides t
16b00 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63  he.** previous c
16b10 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65  all.)^  ^Disable
16b20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
16b30 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20  by installing a 
16b40 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  NULL callback..*
16b50 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
16b60 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
16b70 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54  default..**.** T
16b80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
16b90 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
16ba0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
16bb0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
16bc0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
16bd0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
16be0 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69  oked the authori
16bf0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  zer callback..**
16c00 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
16c10 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
16c20 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
16c30 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
16c40 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
16c50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
16c60 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
16c70 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
16c80 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
16c90 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c  **.** ^When [sql
16ca0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
16cb0 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72  )] is used to pr
16cc0 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e  epare a statemen
16cd0 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  t, the.** statem
16ce0 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d  ent might be re-
16cf0 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20  prepared during 
16d00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
16d10 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63   due to a .** sc
16d20 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65  hema change.  He
16d30 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61  nce, the applica
16d40 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75  tion should ensu
16d50 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63  re that the.** c
16d60 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65  orrect authorize
16d70 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69  r callback remai
16d80 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69  ns in place duri
16d90 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
16da0 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  step()]..**.** ^
16db0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75  Note that the au
16dc0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
16dd0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c  k is invoked onl
16de0 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c  y during.** [sql
16df0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
16e00 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
16e10 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20    Authorization 
16e20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72  is not.** perfor
16e30 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65  med during state
16e40 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  ment evaluation 
16e50 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  in [sqlite3_step
16e60 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61  ()], unless.** a
16e70 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20  s stated in the 
16e80 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
16e90 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ph, sqlite3_step
16ea0 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71  () invokes.** sq
16eb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
16ec0 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20  () to reprepare 
16ed0 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  a statement afte
16ee0 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  r a schema chang
16ef0 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  e..*/.int sqlite
16f00 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
16f10 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
16f20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
16f30 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
16f40 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
16f50 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
16f60 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
16f70 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
16f80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
16f90 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
16fa0 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
16fb0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
16fc0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
16fd0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
16fe0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
16ff0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
17000 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
17010 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
17020 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
17030 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
17040 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
17050 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
17060 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
17070 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
17080 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
17090 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
170a0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
170b0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
170c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
170d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
170e0 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f  ENY   1   /* Abo
170f0 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  rt the SQL state
17100 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72  ment with an err
17110 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
17120 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20  LITE_IGNORE 2   
17130 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61  /* Don't allow a
17140 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74  ccess, but don't
17150 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72   generate an err
17160 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  or */../*.** CAP
17170 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
17180 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a  r Action Codes.*
17190 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
171a0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
171b0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
171c0 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
171d0 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74  ck function.** t
171e0 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74  hat is invoked t
171f0 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74  o authorize cert
17200 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ain SQL statemen
17210 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a  t actions.  The.
17220 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
17230 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ter to the callb
17240 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ack is an intege
17250 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63  r code that spec
17260 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63  ifies.** what ac
17270 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75  tion is being au
17280 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65  thorized.  These
17290 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72   are the integer
172a0 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68   action codes th
172b0 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  at.** the author
172c0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61  izer callback ma
172d0 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a  y be passed..**.
172e0 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20  ** These action 
172f0 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e  code values sign
17300 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  ify what kind of
17310 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f   operation is to
17320 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65   be.** authorize
17330 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20  d.  The 3rd and 
17340 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  4th parameters t
17350 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74  o the authorizat
17360 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  ion.** callback 
17370 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65  function will be
17380 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e   parameters or N
17390 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ULL depending on
173a0 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a   which of these.
173b0 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64  ** codes is used
173c0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
173d0 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20  arameter.  ^The 
173e0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
173f0 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
17400 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
17410 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
17420 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c  atabase ("main",
17430 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e   "temp",.** etc.
17440 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e  ) if applicable.
17450 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
17460 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
17470 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
17480 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
17490 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
174a0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
174b0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
174c0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
174d0 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
174e0 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
174f0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
17500 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
17510 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
17520 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
17530 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17540 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
17550 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
17560 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
17570 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
17580 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
17590 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
175a0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
175b0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
175c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
175d0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
175e0 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
175f0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
17600 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17610 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17620 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
17630 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
17640 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
17650 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
17660 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
17670 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
17680 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
17690 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
176a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
176b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
176c0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
176d0 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
176e0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
176f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
17700 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17710 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
17720 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
17730 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
17740 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17750 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17760 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
17770 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
17780 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
17790 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
177a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
177b0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
177c0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
177d0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
177e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
177f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17800 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
17810 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
17820 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
17830 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17840 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
17850 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
17860 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
17870 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
17880 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
17890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
178a0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
178b0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
178c0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
178d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
178e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
178f0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
17900 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
17910 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
17920 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
17930 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
17940 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
17950 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
17960 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
17970 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
17980 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
17990 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
179a0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
179b0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
179c0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
179d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
179e0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
179f0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
17a00 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
17a10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
17a20 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
17a30 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
17a40 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
17a50 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
17a60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
17a70 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
17a80 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
17a90 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
17aa0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
17ab0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
17ac0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
17ad0 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
17ae0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
17af0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
17b00 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
17b10 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
17b20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
17b30 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
17b40 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
17b50 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
17b60 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
17b70 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
17b80 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
17b90 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
17ba0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17bb0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
17bc0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
17bd0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17be0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
17bf0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17c00 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
17c10 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
17c20 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
17c30 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
17c40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17c50 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
17c60 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
17c70 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
17c80 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
17c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17ca0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
17cb0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
17cc0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
17cd0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
17ce0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17cf0 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
17d00 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
17d10 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
17d20 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
17d30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
17d40 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
17d50 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
17d60 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
17d70 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
17d80 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
17d90 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
17da0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
17db0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
17dc0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
17dd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
17de0 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
17df0 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
17e00 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
17e10 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
17e20 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
17e30 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
17e40 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
17e50 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
17e60 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
17e70 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
17e80 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
17e90 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
17ea0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
17eb0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
17ec0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
17ed0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
17ee0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
17ef0 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
17f00 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
17f10 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
17f20 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
17f30 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
17f40 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
17f50 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
17f60 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
17f70 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
17f80 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
17f90 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
17fa0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
17fb0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
17fc0 63 74 69 6f 6e 73 0a 2a 2a 20 45 58 50 45 52 49  ctions.** EXPERI
17fd0 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54 68 65  MENTAL.**.** The
17fe0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
17ff0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
18000 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
18010 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
18020 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
18030 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
18040 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
18050 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
18060 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
18070 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
18080 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
18090 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
180a0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
180b0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
180c0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
180d0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
180e0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
180f0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
18100 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18110 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
18120 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
18130 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
18140 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
18150 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
18160 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
18170 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
18180 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
18190 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
181a0 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
181b0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
181c0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
181d0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
181e0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
181f0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
18200 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
18210 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
18220 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
18230 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
18240 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
18250 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
18260 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
18270 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
18280 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
18290 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
182a0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
182b0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
182c0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
182d0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
182e0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
182f0 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
18300 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
18310 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
18320 20 72 75 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   run..*/.SQLITE_
18330 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
18340 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
18350 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
18360 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
18370 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
18380 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
18390 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
183a0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
183b0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
183c0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
183d0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
183e0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
183f0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
18400 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
18410 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
18420 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
18430 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73 20  tine configures 
18440 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
18450 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72 6f  ion - the.** pro
18460 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 2d  gress callback -
18470 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
18480 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
18490 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75 6e  ring long.** run
184a0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b 73  ning calls to [s
184b0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
184c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
184d0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
184e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20 20  _get_table()].  
184f0 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66  An example use f
18500 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  or this.** inter
18510 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20  face is to keep 
18520 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75  a GUI updated du
18530 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65  ring a large que
18540 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ry..**.** ^If th
18550 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
18560 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
18570 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
18580 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
18590 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
185a0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
185b0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
185c0 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
185d0 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
185e0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
185f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
18600 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  ess handler must
18610 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
18620 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
18630 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
18640 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
18650 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72  t invoked the pr
18660 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
18670 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
18680 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
18690 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
186a0 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
186b0 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
186c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
186d0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
186e0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
186f0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
18700 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ..**.*/.void sql
18710 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
18720 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
18730 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  int, int(*)(void
18740 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
18750 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65  ** CAPI3REF: Ope
18760 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62  ning A New Datab
18770 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
18780 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
18790 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c  ines open an SQL
187a0 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ite database fil
187b0 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20  e whose name is 
187c0 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20  given by the.** 
187d0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
187e0 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
187f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
18800 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
18810 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
18820 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
18830 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
18840 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
18850 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
18860 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
18870 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
18880 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
18890 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
188a0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
188b0 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
188c0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
188d0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
188e0 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
188f0 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
18900 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
18910 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
18920 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
18930 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
18940 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
18950 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
18960 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
18970 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
18980 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
18990 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
189a0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
189b0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
189c0 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
189d0 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
189e0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
189f0 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
18a00 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
18a10 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
18a20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
18a30 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
18a40 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
18a50 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
18a60 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
18a70 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
18a80 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
18a90 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
18aa0 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
18ab0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
18ac0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
18ad0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
18ae0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
18af0 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64  coding for the d
18b00 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
18b10 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69  UTF-8 if.** sqli
18b20 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
18b30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
18b40 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a  is called and.**
18b50 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
18b60 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
18b70 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   if sqlite3_open
18b80 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a  16() is used..**
18b90 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
18ba0 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
18bb0 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
18bc0 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
18bd0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
18be0 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
18bf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
18c00 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
18c10 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
18c20 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
18c30 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
18c40 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
18c50 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
18c60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
18c70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
18c80 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
18c90 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
18ca0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
18cb0 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
18cc0 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
18cd0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
18ce0 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
18cf0 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
18d00 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
18d10 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
18d20 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
18d30 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
18d40 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
18d50 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
18d60 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
18d70 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
18d80 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
18d90 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
18da0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
18db0 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
18dc0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
18dd0 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  CHE],.** and/or 
18de0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
18df0 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73  VATECACHE] flags
18e00 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  :)^.**.** <dl>.*
18e10 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
18e20 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f  OPEN_READONLY]</
18e30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
18e40 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
18e50 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  d in read-only m
18e60 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74  ode.  If the dat
18e70 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a  abase does not.*
18e80 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c  * already exist,
18e90 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
18ea0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
18eb0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
18ec0 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
18ed0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
18ee0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
18ef0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
18f00 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20   and writing if 
18f10 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61  possible, or rea
18f20 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20  ding.** only if 
18f30 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74  the file is writ
18f40 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74  e protected by t
18f50 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
18f60 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a  tem.  In either.
18f70 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61  ** case the data
18f80 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64  base must alread
18f90 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69  y exist, otherwi
18fa0 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  se an error is r
18fb0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
18fc0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
18fd0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
18fe0 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
18ff0 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a  EN_CREATE]</dt>.
19000 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62  ** <dd>The datab
19010 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
19020 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72  r reading and wr
19030 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72  iting, and is cr
19040 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69  eates it if.** i
19050 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
19060 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
19070 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
19080 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
19090 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
190a0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
190b0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
190c0 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
190d0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
190e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
190f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
19100 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
19110 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
19120 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20   shown above or 
19130 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69  one of the combi
19140 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
19150 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20  ove combined.** 
19160 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
19170 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
19180 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
19190 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c  LMUTEX],.** [SQL
191a0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
191b0 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51  ACHE] and/or [SQ
191c0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
191d0 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a  CACHE] flags,.**
191e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
191f0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
19200 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
19210 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
19220 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
19230 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
19240 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
19250 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
19260 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
19270 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
19280 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
19290 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
192a0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
192b0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
192c0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
192d0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
192e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
192f0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
19300 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
19310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
19320 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
19330 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
19340 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
19350 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
19360 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
19370 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
19380 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
19390 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
193a0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
193b0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
193c0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
193d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
193e0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
193f0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
19400 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
19410 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
19420 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
19430 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
19440 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
19450 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
19460 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
19470 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
19480 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
19490 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
194a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
194b0 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
194c0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
194d0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
194e0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
194f0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
19500 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
19510 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
19520 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
19530 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
19540 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
19550 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
19560 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
19570 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
19580 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
19590 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
195a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
195b0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
195c0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
195d0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
195e0 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
195f0 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
19600 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
19610 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
19620 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
19630 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
19640 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
19650 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
19660 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
19670 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
19680 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
19690 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
196a0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
196b0 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
196c0 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
196d0 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
196e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
196f0 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
19700 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
19710 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
19720 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
19730 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
19740 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
19750 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
19760 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
19770 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
19780 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
19790 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
197a0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
197b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
197c0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
197d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
197e0 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
197f0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
19800 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
19810 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
19820 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
19830 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
19840 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
19850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
19860 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
19870 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
19880 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
19890 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
198a0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
198b0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
198c0 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
198d0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
198e0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
198f0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
19900 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
19910 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
19920 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
19930 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
19940 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
19950 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
19960 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
19970 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
19980 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
19990 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
199a0 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
199b0 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
199c0 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
199d0 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
199e0 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
199f0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
19a00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19a10 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
19a20 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
19a30 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
19a40 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
19a50 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
19a60 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
19a70 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
19a80 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
19a90 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
19aa0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
19ab0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
19ac0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
19ad0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
19ae0 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
19af0 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
19b00 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
19b10 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
19b20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
19b30 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
19b40 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
19b50 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
19b60 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
19b70 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
19b80 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
19b90 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
19ba0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
19bb0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
19bc0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
19bd0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
19be0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
19bf0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
19c00 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
19c10 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
19c20 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
19c30 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
19c40 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
19c50 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
19c60 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
19c70 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
19c80 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
19c90 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
19ca0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
19cb0 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
19cc0 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
19cd0 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
19ce0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19cf0 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
19d00 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
19d10 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
19d20 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
19d30 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
19d40 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
19d50 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
19d60 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
19d70 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
19d80 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
19d90 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
19da0 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
19db0 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
19dc0 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
19dd0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
19de0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
19df0 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
19e00 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
19e10 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
19e20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
19e30 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
19e40 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
19e50 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
19e60 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
19e70 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
19e80 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
19e90 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
19ea0 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
19eb0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
19ec0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
19ed0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
19ee0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
19ef0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
19f00 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
19f10 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
19f20 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
19f30 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
19f40 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
19f50 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
19f60 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
19f70 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
19f80 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
19f90 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
19fa0 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
19fb0 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65  ons.)^.**.** Whe
19fc0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
19fd0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
19fe0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
19ff0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
1a000 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
1a010 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
1a020 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
1a030 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
1a040 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
1a050 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
1a060 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
1a070 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
1a080 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
1a090 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
1a0a0 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
1a0b0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
1a0c0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
1a0d0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
1a0e0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1a0f0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
1a100 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
1a110 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
1a120 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
1a130 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
1a140 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
1a150 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
1a160 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
1a170 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
1a180 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
1a190 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
1a1a0 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
1a1b0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
1a1c0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
1a1d0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
1a1e0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
1a1f0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
1a200 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
1a210 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
1a220 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
1a230 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
1a240 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
1a250 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
1a260 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
1a270 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
1a280 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
1a290 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
1a2a0 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
1a2b0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
1a2c0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
1a2d0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
1a2e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
1a2f0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1a300 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
1a310 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1a320 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
1a330 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1a340 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
1a350 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
1a360 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
1a370 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  6(sqlite3*);../*
1a380 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1a390 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
1a3a0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
1a3b0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1a3c0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
1a3d0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
1a3e0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
1a3f0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
1a400 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
1a410 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1a420 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
1a430 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
1a440 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
1a450 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
1a460 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
1a470 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
1a480 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
1a490 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
1a4a0 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
1a4b0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
1a4c0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
1a4d0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
1a4e0 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
1a4f0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1a500 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1a510 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
1a520 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
1a530 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
1a540 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
1a550 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
1a560 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1a570 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
1a580 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
1a590 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
1a5a0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
1a5b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1a5c0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
1a5d0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
1a5e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
1a5f0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
1a600 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
1a610 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
1a620 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
1a630 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
1a640 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
1a650 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
1a660 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1a670 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
1a680 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
1a690 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
1a6a0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
1a6b0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
1a6c0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1a6d0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
1a6e0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1a6f0 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
1a700 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
1a710 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
1a720 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
1a730 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
1a740 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
1a750 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
1a760 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
1a770 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
1a780 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
1a790 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
1a7a0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1a7b0 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
1a7c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a7d0 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
1a7e0 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
1a7f0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
1a800 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a810 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
1a820 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
1a830 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
1a840 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
1a850 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
1a860 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
1a870 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
1a880 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
1a890 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
1a8a0 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e 63  truct.  The func
1a8b0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1a8c0 20 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a 2a   old limit.)^.**
1a8d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
1a8e0 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
1a8f0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
1a900 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
1a910 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68 65  ed..** ^(For the
1a920 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
1a930 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  of SQLITE_LIMIT_
1a940 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20 0a  XYZ there is a .
1a950 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
1a960 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
1a970 2a 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70 69  * set by a compi
1a980 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72 6f  le-time C prepro
1a990 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61 6d  cessor macro nam
1a9a0 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  ed .** [limits |
1a9b0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a 5d   SQLITE_MAX_XYZ]
1a9c0 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
1a9d0 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
1a9e0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
1a9f0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
1aa00 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
1aa10 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
1aa20 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
1aa30 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
1aa40 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
1aa50 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
1aa60 72 20 6c 69 6d 69 74 2e 0a 2a 2a 0a 2a 2a 20 52  r limit..**.** R
1aa70 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
1aa80 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
1aa90 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
1aaa0 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
1aab0 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
1aac0 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
1aad0 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
1aae0 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
1aaf0 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
1ab00 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
1ab10 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
1ab20 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
1ab30 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
1ab40 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
1ab50 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
1ab60 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
1ab70 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
1ab80 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
1ab90 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
1aba0 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
1abb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
1abc0 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
1abd0 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
1abe0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
1abf0 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
1ac00 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
1ac10 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
1ac20 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
1ac30 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
1ac40 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
1ac50 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
1ac60 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
1ac70 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
1ac80 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
1ac90 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
1aca0 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
1acb0 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
1acc0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
1acd0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1ace0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
1acf0 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
1ad00 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
1ad10 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
1ad20 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
1ad30 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
1ad40 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
1ad50 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
1ad60 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
1ad70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1ad80 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
1ad90 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
1ada0 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
1adb0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
1adc0 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
1add0 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
1ade0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
1adf0 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
1ae00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1ae10 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
1ae20 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
1ae30 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
1ae40 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
1ae50 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
1ae60 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
1ae70 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
1ae80 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
1ae90 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
1aea0 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
1aeb0 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
1aec0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
1aed0 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
1aee0 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
1aef0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
1af00 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
1af10 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
1af20 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
1af30 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
1af40 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
1af50 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
1af60 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e  * <dl>.** ^(<dt>
1af70 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
1af80 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
1af90 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  The maximum size
1afa0 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f   of any string o
1afb0 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20  r BLOB or table 
1afc0 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  row.<dd>)^.**.**
1afd0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1afe0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
1aff0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1b000 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1b010 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1b020 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
1b030 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1b040 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
1b050 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1b060 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1b070 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
1b080 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
1b090 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
1b0a0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
1b0b0 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
1b0c0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1b0d0 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
1b0e0 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
1b0f0 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
1b100 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
1b110 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1b120 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1b130 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1b140 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1b150 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
1b160 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
1b170 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
1b180 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1b190 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1b1a0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
1b1b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1b1c0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
1b1d0 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
1b1e0 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1b1f0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1b200 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1b210 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
1b220 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1b230 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
1b240 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
1b250 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
1b260 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
1b270 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
1b280 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
1b290 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1b2a0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1b2b0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
1b2c0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1b2d0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
1b2e0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
1b2f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1b300 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
1b310 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
1b320 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1b330 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
1b340 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
1b350 61 62 61 73 65 73 5d 2e 3c 2f 64 64 3e 0a 2a 2a  abases].</dd>.**
1b360 0a 2a 2a 20 5e 3c 64 74 3e 53 51 4c 49 54 45 5f  .** ^<dt>SQLITE_
1b370 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
1b380 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
1b390 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1b3a0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
1b3b0 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
1b3c0 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
1b3d0 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
1b3e0 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
1b3f0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1b400 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
1b410 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
1b420 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1b430 75 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c  umber of variabl
1b440 65 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  es in an SQL sta
1b450 74 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a  tement that can.
1b460 2a 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64  ** be bound.</dd
1b470 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1b480 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
1b490 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  GGER_DEPTH</dt>.
1b4a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1b4b0 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75  um depth of recu
1b4c0 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65  rsion for trigge
1b4d0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f  rs.</dd>)^.** </
1b4e0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
1b4f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
1b500 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
1b510 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
1b520 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
1b530 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1b540 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
1b550 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1b560 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20  LUMN            
1b570 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
1b580 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  e SQLITE_LIMIT_E
1b590 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  XPR_DEPTH       
1b5a0 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
1b5b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1b5c0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20  COMPOUND_SELECT 
1b5d0 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
1b5e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1b5f0 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20  _VDBE_OP        
1b600 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
1b610 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1b620 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20  T_FUNCTION_ARG  
1b630 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64              6.#d
1b640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1b650 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20  IT_ATTACHED     
1b660 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23               7.#
1b670 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1b680 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1b690 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a  _LENGTH       8.
1b6a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1b6b0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1b6c0 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39  MBER           9
1b6d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b6e0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
1b6f0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31  PTH            1
1b700 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
1b710 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
1b720 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
1b730 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
1b740 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
1b750 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  er}.**.** To exe
1b760 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
1b770 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
1b780 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
1b790 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
1b7a0 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
1b7b0 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
1b7c0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
1b7d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
1b7e0 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
1b7f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b800 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1b810 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
1b820 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
1b830 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
1b840 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1b850 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1b860 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
1b870 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1b880 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
1b890 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
1b8a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
1b8b0 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
1b8c0 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
1b8d0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
1b8e0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
1b8f0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
1b900 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
1b910 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1b920 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1b930 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
1b940 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
1b950 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
1b960 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
1b970 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1b980 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
1b990 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
1b9a0 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
1b9b0 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  nt is less than 
1b9c0 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20  zero, then zSql 
1b9d0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
1b9e0 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
1b9f0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
1ba00 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
1ba10 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  ative, then it i
1ba20 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1ba30 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65   number of  byte
1ba40 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c  s read from zSql
1ba50 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69  .  ^When nByte i
1ba60 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
1ba70 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69  the.** zSql stri
1ba80 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65  ng ends at eithe
1ba90 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30  r the first '\00
1baa0 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63  0' or '\u0000' c
1bab0 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74  haracter or.** t
1bac0 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65  he nByte-th byte
1bad0 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65  , whichever come
1bae0 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20  s first. If the 
1baf0 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20  caller knows.** 
1bb00 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
1bb10 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
1bb20 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
1bb30 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c   there is a smal
1bb40 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65  l.** performance
1bb50 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65   advantage to be
1bb60 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69   gained by passi
1bb70 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61  ng an nByte para
1bb80 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73  meter that.** is
1bb90 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75   equal to the nu
1bba0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
1bbb0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1bbc0 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
1bbd0 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
1bbe0 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a  rminator bytes..
1bbf0 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
1bc00 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
1bc10 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
1bc20 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
1bc30 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
1bc40 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
1bc50 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
1bc60 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
1bc70 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
1bc80 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
1bc90 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
1bca0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
1bcb0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
1bcc0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
1bcd0 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
1bce0 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
1bcf0 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
1bd00 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
1bd10 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
1bd20 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1bd30 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
1bd40 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1bd50 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
1bd60 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
1bd70 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
1bd80 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
1bd90 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
1bda0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
1bdb0 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
1bdc0 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
1bdd0 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
1bde0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
1bdf0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
1be00 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
1be10 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
1be20 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
1be30 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
1be40 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
1be50 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
1be60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
1be70 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
1be80 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
1be90 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
1bea0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
1beb0 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
1bec0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1bed0 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
1bee0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
1bef0 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
1bf00 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
1bf10 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
1bf20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1bf30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1bf40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
1bf50 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
1bf60 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
1bf70 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
1bf80 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
1bf90 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
1bfa0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
1bfb0 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
1bfc0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1bfd0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
1bfe0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
1bff0 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
1c000 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
1c010 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
1c020 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
1c030 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
1c040 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
1c050 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
1c060 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
1c070 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
1c080 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
1c090 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
1c0a0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
1c0b0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
1c0c0 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
1c0d0 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
1c0e0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
1c0f0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1c100 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
1c110 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
1c120 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
1c130 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
1c140 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
1c150 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1c160 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
1c170 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
1c180 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
1c190 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
1c1a0 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 5e 49  un it again.  ^I
1c1b0 66 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73  f the schema has
1c1c0 20 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61   changed in.** a
1c1d0 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
1c1e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f  the statement no
1c1f0 20 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b   longer valid, [
1c200 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c210 77 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65  will still.** re
1c220 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48  turn [SQLITE_SCH
1c230 45 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b  EMA].  But unlik
1c240 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
1c250 61 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53  avior, [SQLITE_S
1c260 43 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77  CHEMA] is.** now
1c270 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20   a fatal error. 
1c280 20 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   Calling [sqlite
1c290 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1c2a0 61 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d  again will not m
1c2b0 61 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  ake the.** error
1c2c0 20 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a   go away.  Note:
1c2d0 20 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72   use [sqlite3_er
1c2e0 72 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20  rmsg()] to find 
1c2f0 74 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74  the text.** of t
1c300 68 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72  he parsing error
1c310 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e   that results in
1c320 20 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45   an [SQLITE_SCHE
1c330 4d 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c  MA] return..** <
1c340 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1c350 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
1c360 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
1c370 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1c380 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
1c390 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
1c3a0 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
1c3b0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
1c3c0 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
1c3d0 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
1c3e0 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
1c3f0 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
1c400 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
1c410 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
1c420 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
1c430 0a 2a 2a 20 61 6e 64 20 79 6f 75 20 77 6f 75 6c  .** and you woul
1c440 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
1c450 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
1c460 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
1c470 5d 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  ] in order.** to
1c480 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
1c490 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
1c4a0 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
1c4b0 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
1c4c0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
1c4d0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
1c4e0 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
1c4f0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
1c500 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
1c510 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
1c520 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
1c530 65 20 6f 66 20 61 20 5b 70 61 72 61 6d 65 74 65  e of a [paramete
1c540 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74  r | host paramet
1c550 65 72 5d 20 69 6e 20 74 68 65 20 57 48 45 52 45  er] in the WHERE
1c560 20 63 6c 61 75 73 65 20 6d 69 67 68 74 0a 2a 2a   clause might.**
1c570 20 63 68 61 6e 67 65 20 74 68 65 20 71 75 65 72   change the quer
1c580 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
1c590 74 65 6d 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  tement, then the
1c5a0 20 73 74 61 74 65 6d 65 6e 74 20 6d 61 79 20 62   statement may b
1c5b0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
1c5c0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 20 28 61  ly recompiled (a
1c5d0 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
1c5e0 65 65 6e 20 61 20 73 63 68 65 6d 61 20 63 68 61  een a schema cha
1c5f0 6e 67 65 29 20 6f 6e 20 74 68 65 20 66 69 72 73  nge) on the firs
1c600 74 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  t .** [sqlite3_s
1c610 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c  tep()] call foll
1c620 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65  owing any change
1c630 20 74 6f 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   to the .** [sql
1c640 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
1c650 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
1c660 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a  e [parameter]. .
1c670 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
1c680 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
1c690 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
1c6a0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1c6b0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1c6c0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1c6d0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1c6e0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1c6f0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1c700 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1c710 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1c720 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1c730 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1c740 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1c750 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1c760 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1c770 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1c780 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1c790 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1c7a0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1c7b0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1c7c0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1c7d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
1c7e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1c7f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1c800 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1c810 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1c820 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1c830 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1c840 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1c850 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1c860 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1c870 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1c880 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1c890 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1c8a0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1c8b0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1c8c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1c8d0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1c8e0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1c8f0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1c900 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1c910 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1c920 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
1c930 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1c940 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1c950 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1c960 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1c970 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1c980 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1c990 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1c9a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1c9b0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1c9c0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1c9d0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1c9e0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1c9f0 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1ca00 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1ca10 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1ca20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1ca30 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1ca40 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1ca50 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1ca60 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
1ca70 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1ca80 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1ca90 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1caa0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1cab0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1cac0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1cad0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1cae0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1caf0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1cb00 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1cb10 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1cb20 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1cb30 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1cb40 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1cb50 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1cb60 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1cb70 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1cb80 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1cb90 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
1cba0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1cbb0 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
1cbc0 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
1cbd0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
1cbe0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
1cbf0 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
1cc00 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
1cc10 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
1cc20 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
1cc30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1cc40 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
1cc50 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
1cc60 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1cc70 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1cc80 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
1cc90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1cca0 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  v2()]..*/.const 
1ccb0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
1ccc0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
1ccd0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1cce0 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
1ccf0 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
1cd00 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
1cd10 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
1cd20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
1cd30 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
1cd40 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
1cd50 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
1cd60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1cd70 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
1cd80 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
1cd90 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
1cda0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
1cdb0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
1cdc0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
1cdd0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
1cde0 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
1cdf0 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
1ce00 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
1ce10 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
1ce20 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
1ce30 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
1ce40 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
1ce50 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
1ce60 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
1ce70 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
1ce80 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
1ce90 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
1cea0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
1ceb0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
1cec0 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
1ced0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
1cee0 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
1cef0 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
1cf00 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
1cf10 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
1cf20 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1cf30 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
1cf40 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
1cf50 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
1cf60 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
1cf70 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
1cf80 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
1cf90 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
1cfa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
1cfb0 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
1cfc0 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
1cfd0 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
1cfe0 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
1cff0 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
1d000 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72  s held.  A inter
1d010 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
1d020 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
1d030 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1d040 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
1d050 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
1d060 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1d070 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
1d080 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
1d090 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
1d0a0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
1d0b0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
1d0c0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1d0d0 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
1d0e0 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
1d0f0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
1d100 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
1d110 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
1d120 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
1d130 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
1d140 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
1d150 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
1d160 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
1d170 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
1d180 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
1d190 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
1d1a0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1d1b0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1d1c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1d1d0 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
1d1e0 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
1d1f0 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
1d200 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
1d210 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
1d220 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
1d230 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
1d240 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
1d250 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
1d260 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 62 65  ction between be
1d270 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
1d280 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
1d290 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1d2a0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
1d2b0 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
1d2c0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1d2d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
1d2e0 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
1d2f0 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
1d300 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
1d310 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
1d320 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
1d330 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
1d340 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
1d350 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
1d360 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
1d370 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
1d380 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
1d390 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
1d3a0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
1d3b0 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
1d3c0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1d3d0 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
1d3e0 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
1d3f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
1d400 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
1d410 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
1d420 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
1d430 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
1d440 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
1d450 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
1d460 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
1d470 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
1d480 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1d490 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
1d4a0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
1d4b0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
1d4c0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
1d4d0 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
1d4e0 20 4f 62 6a 65 63 74 20 7b 48 31 36 30 30 31 7d   Object {H16001}
1d4f0 20 3c 53 32 30 32 30 30 3e 0a 2a 2a 0a 2a 2a 20   <S20200>.**.** 
1d500 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
1d510 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
1d520 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
1d530 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
1d540 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
1d550 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
1d560 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
1d570 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
1d580 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
1d590 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1d5a0 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
1d5b0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1d5c0 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
1d5d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1d5e0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
1d5f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
1d600 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
1d610 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
1d620 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
1d630 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
1d640 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
1d650 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
1d660 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
1d670 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
1d680 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
1d690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
1d6a0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
1d6b0 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
1d6c0 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
1d6d0 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
1d6e0 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
1d6f0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1d700 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
1d710 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
1d720 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d730 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
1d740 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
1d750 74 65 6d 65 6e 74 73 20 7b 48 31 33 35 30 30 7d  tements {H13500}
1d760 20 3c 53 37 30 33 30 30 3e 0a 2a 2a 20 4b 45 59   <S70300>.** KEY
1d770 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72  WORDS: {host par
1d780 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61  ameter} {host pa
1d790 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20  rameters} {host 
1d7a0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a  parameter name}.
1d7b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
1d7c0 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51  L parameter} {SQ
1d7d0 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70  L parameters} {p
1d7e0 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
1d7f0 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  }.**.** ^(In the
1d800 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1d810 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
1d820 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1d830 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
1d840 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
1d850 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
1d860 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
1d870 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
1d880 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
1d890 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
1d8a0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
1d8b0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
1d8c0 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
1d8d0 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
1d8e0 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
1d8f0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
1d900 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
1d910 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
1d920 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
1d930 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
1d940 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
1d950 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
1d960 6e 74 69 66 65 72 2e 29 5e 20 20 5e 54 68 65 20  ntifer.)^  ^The 
1d970 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
1d980 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
1d990 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
1d9a0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
1d9b0 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
1d9c0 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
1d9d0 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
1d9e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1d9f0 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
1da00 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
1da10 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1da20 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1da30 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1da40 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
1da50 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1da60 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1da70 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
1da80 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
1da90 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
1daa0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
1dab0 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
1dac0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
1dad0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
1dae0 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
1daf0 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
1db00 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
1db10 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
1db20 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
1db30 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
1db40 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
1db50 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
1db60 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
1db70 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
1db80 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
1db90 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
1dba0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
1dbb0 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
1dbc0 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
1dbd0 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
1dbe0 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
1dbf0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
1dc00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1dc10 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
1dc20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
1dc30 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
1dc40 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
1dc50 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1dc60 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
1dc70 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
1dc80 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
1dc90 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
1dca0 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
1dcb0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
1dcc0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
1dcd0 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
1dce0 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
1dcf0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
1dd00 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
1dd10 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
1dd20 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  meter..**.** ^(I
1dd30 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
1dd40 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
1dd50 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
1dd60 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
1dd70 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
1dd80 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
1dd90 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
1dda0 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
1ddb0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1ddc0 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
1ddd0 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
1dde0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1ddf0 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
1de00 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1de10 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69  ameter is negati
1de20 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  ve, the length o
1de30 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
1de40 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1de50 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
1de60 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
1de70 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  inator..**.** ^T
1de80 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1de90 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
1dea0 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
1deb0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
1dec0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
1ded0 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
1dee0 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
1def0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
1df00 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
1df10 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
1df20 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
1df30 69 74 68 20 69 74 2e 20 5e 49 66 20 74 68 65 20  ith it. ^If the 
1df40 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
1df50 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
1df60 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
1df70 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
1df80 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
1df90 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
1dfa0 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
1dfb0 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
1dfc0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
1dfd0 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
1dfe0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
1dff0 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
1e000 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
1e010 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
1e020 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
1e030 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
1e040 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
1e050 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
1e060 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
1e070 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1e080 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
1e090 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e0a0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1e0b0 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
1e0c0 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
1e0d0 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
1e0e0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
1e0f0 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
1e100 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
1e110 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
1e120 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
1e130 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
1e140 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
1e150 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
1e160 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
1e170 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
1e180 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
1e190 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
1e1a0 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
1e1b0 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
1e1c0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1e1d0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
1e1e0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
1e1f0 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
1e200 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
1e210 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
1e220 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
1e230 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
1e240 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
1e250 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
1e260 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
1e270 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
1e280 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1e290 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
1e2a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1e2b0 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
1e2c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
1e2d0 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
1e2e0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
1e2f0 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
1e300 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
1e310 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
1e320 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
1e330 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
1e340 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
1e350 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
1e360 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
1e370 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
1e380 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1e390 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
1e3a0 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
1e3b0 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
1e3c0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
1e3d0 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
1e3e0 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
1e3f0 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
1e400 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
1e410 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
1e420 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
1e430 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
1e440 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
1e450 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e460 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
1e470 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1e480 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
1e490 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
1e4a0 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
1e4b0 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
1e4c0 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
1e4d0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
1e4e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
1e4f0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
1e500 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
1e510 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
1e520 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
1e530 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
1e540 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1e550 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1e560 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
1e570 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1e580 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
1e590 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
1e5a0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1e5b0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
1e5c0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
1e5d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1e5e0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1e5f0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
1e600 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
1e610 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
1e620 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1e630 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
1e640 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
1e650 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1e660 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
1e670 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
1e680 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
1e690 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
1e6a0 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
1e6b0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
1e6c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
1e6d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1e6e0 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
1e6f0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
1e700 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
1e710 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
1e720 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1e730 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
1e740 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
1e750 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
1e760 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
1e770 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1e780 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
1e790 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
1e7a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
1e7b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1e7c0 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
1e7d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
1e7e0 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
1e7f0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
1e800 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
1e810 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1e820 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
1e830 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
1e840 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
1e850 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
1e860 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1e870 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
1e880 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
1e890 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
1e8a0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
1e8b0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
1e8c0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
1e8d0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
1e8e0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
1e8f0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
1e900 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
1e910 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
1e920 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
1e930 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
1e940 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
1e950 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
1e960 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
1e970 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
1e980 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
1e990 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
1e9a0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
1e9b0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
1e9c0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
1e9d0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
1e9e0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
1e9f0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
1ea00 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
1ea10 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
1ea20 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
1ea30 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
1ea40 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1ea50 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
1ea60 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
1ea70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1ea80 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
1ea90 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1eaa0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1eab0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
1eac0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
1ead0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
1eae0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
1eaf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1eb00 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
1eb10 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
1eb20 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
1eb30 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
1eb40 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
1eb50 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
1eb60 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
1eb70 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
1eb80 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
1eb90 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
1eba0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
1ebb0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
1ebc0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
1ebd0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
1ebe0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
1ebf0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
1ec00 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
1ec10 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
1ec20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
1ec30 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
1ec40 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
1ec50 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
1ec60 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
1ec70 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
1ec80 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
1ec90 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
1eca0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
1ecb0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
1ecc0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
1ecd0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
1ece0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 61 6c 73 6f  .** and are also
1ecf0 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
1ed00 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
1ed10 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
1ed20 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
1ed30 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
1ed40 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
1ed50 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
1ed60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
1ed70 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
1ed80 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
1ed90 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
1eda0 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
1edb0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
1edc0 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
1edd0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
1ede0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
1edf0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
1ee00 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
1ee10 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
1ee20 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
1ee30 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
1ee40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ee50 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
1ee60 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1ee70 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
1ee80 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
1ee90 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
1eea0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
1eeb0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
1eec0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
1eed0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
1eee0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
1eef0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
1ef00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
1ef10 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1ef20 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
1ef30 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
1ef40 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
1ef50 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
1ef60 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
1ef70 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
1ef80 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
1ef90 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
1efa0 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
1efb0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
1efc0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
1efd0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
1efe0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
1eff0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
1f000 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1f010 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
1f020 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
1f030 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
1f040 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
1f050 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
1f060 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
1f070 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
1f080 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
1f090 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
1f0a0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
1f0b0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
1f0c0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
1f0d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f0e0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
1f0f0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1f100 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
1f110 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
1f120 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1f130 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
1f140 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
1f150 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1f160 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
1f170 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1f180 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1f190 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
1f1a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
1f1b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f1c0 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
1f1d0 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
1f1e0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
1f1f0 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
1f200 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
1f210 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
1f220 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
1f230 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
1f240 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
1f250 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
1f260 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
1f270 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
1f280 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
1f290 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
1f2a0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
1f2b0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
1f2c0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
1f2d0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
1f2e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1f2f0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
1f300 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
1f310 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  lt Set.**.** ^Re
1f320 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
1f330 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
1f340 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
1f350 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
1f360 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f370 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
1f380 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
1f390 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
1f3a0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
1f3b0 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
1f3c0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
1f3d0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
1f3e0 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
1f3f0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
1f400 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
1f410 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
1f420 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
1f430 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
1f440 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  et.**.** ^These 
1f450 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1f460 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
1f470 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
1f480 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
1f490 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
1f4a0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
1f4b0 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
1f4c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
1f4d0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
1f4e0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1f4f0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
1f500 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1f510 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
1f520 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
1f530 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
1f540 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
1f550 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1f560 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
1f570 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1f580 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
1f590 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
1f5a0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
1f5b0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
1f5c0 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
1f5d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
1f5e0 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
1f5f0 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
1f600 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
1f610 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
1f620 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
1f630 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
1f640 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
1f650 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
1f660 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
1f670 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
1f680 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1f690 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
1f6a0 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a  e next call to.*
1f6b0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
1f6c0 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74  _name() or sqlit
1f6d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
1f6e0 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63  () on the same c
1f6f0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  olumn..**.** ^If
1f700 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f710 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74  ) fails during t
1f720 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66  he processing of
1f730 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a   either routine.
1f740 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ** (for example 
1f750 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73  during a convers
1f760 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74  ion from UTF-8 t
1f770 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61  o UTF-16) then a
1f780 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1f790 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1f7a0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
1f7b0 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e   a result column
1f7c0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
1f7d0 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65   the "AS" clause
1f7e0 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c   for.** that col
1f7f0 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73  umn, if there is
1f800 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20   an AS clause.  
1f810 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41  If there is no A
1f820 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e  S clause.** then
1f830 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1f840 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65   column is unspe
1f850 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63  cified and may c
1f860 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e  hange from.** on
1f870 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  e release of SQL
1f880 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ite to the next.
1f890 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1f8a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
1f8b0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1f8c0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74  *, int N);.const
1f8d0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
1f8e0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
1f8f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
1f900 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
1f910 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
1f920 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
1f930 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
1f940 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
1f950 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
1f960 65 74 65 72 6d 69 6e 65 20 77 68 61 74 20 63 6f  etermine what co
1f970 6c 75 6d 6e 20 6f 66 20 77 68 61 74 0a 2a 2a 20  lumn of what.** 
1f980 74 61 62 6c 65 20 69 6e 20 77 68 69 63 68 20 64  table in which d
1f990 61 74 61 62 61 73 65 20 61 20 72 65 73 75 6c 74  atabase a result
1f9a0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
1f9b0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 65 73 20 66  tatement comes f
1f9c0 72 6f 6d 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  rom..** ^The nam
1f9d0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1f9e0 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f  e or table or co
1f9f0 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75  lumn can be retu
1fa00 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65  rned as.** eithe
1fa10 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46  r a UTF-8 or UTF
1fa20 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
1fa30 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75  e _database_ rou
1fa40 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tines return.** 
1fa50 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
1fa60 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72  e, the _table_ r
1fa70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
1fa80 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61  he table name, a
1fa90 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e  nd.** the origin
1faa0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
1fab0 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d  n the column nam
1fac0 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  e..** ^The retur
1fad0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61  ned string is va
1fae0 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70  lid until the [p
1faf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fb00 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a  t] is destroyed.
1fb10 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
1fb20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
1fb30 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20   until the same 
1fb40 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72  information is r
1fb50 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69  equested.** agai
1fb60 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74  n in a different
1fb70 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a   encoding..**.**
1fb80 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75   ^The names retu
1fb90 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69  rned are the ori
1fba0 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64  ginal un-aliased
1fbb0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a   names of the.**
1fbc0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
1fbd0 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a  , and column..**
1fbe0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
1fbf0 72 67 75 6d 65 6e 74 20 74 68 65 73 65 20 69 6e  rgument these in
1fc00 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
1fc10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
1fc20 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
1fc30 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
1fc40 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
1fc50 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
1fc60 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
1fc70 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
1fc80 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
1fc90 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
1fca0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
1fcb0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
1fcc0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
1fcd0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 2e  these interface.
1fce0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
1fcf0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
1fd00 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
1fd10 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
1fd20 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
1fd30 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
1fd40 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
1fd50 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
1fd60 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
1fd70 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
1fd80 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
1fd90 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
1fda0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
1fdb0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
1fdc0 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
1fdd0 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
1fde0 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
1fdf0 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
1fe00 62 61 73 65 2c 20 74 61 62 6c 65 0a 2a 2a 20 6f  base, table.** o
1fe10 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
1fe20 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
1fe30 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
1fe40 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
1fe50 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
1fe60 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
1fe70 65 20 70 6f 73 74 66 69 78 65 64 20 77 69 74 68  e postfixed with
1fe80 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20   "16" return.** 
1fe90 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73  UTF-16 encoded s
1fea0 74 72 69 6e 67 73 2c 20 74 68 65 20 6f 74 68 65  trings, the othe
1feb0 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
1fec0 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
1fed0 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
1fee0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
1fef0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
1ff00 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1ff10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
1ff20 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
1ff30 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
1ff40 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
1ff50 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
1ff60 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
1ff70 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
1ff80 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
1ff90 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
1ffa0 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
1ffb0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
1ffc0 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
1ffd0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
1ffe0 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
1fff0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
20000 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
20010 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
20020 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
20030 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
20040 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
20050 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
20060 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
20070 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
20080 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
20090 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
200a0 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
200b0 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
200c0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
200d0 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
200e0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
200f0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
20100 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
20110 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
20120 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
20130 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
20140 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
20150 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
20160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
20170 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
20180 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
20190 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
201a0 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
201b0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
201c0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
201d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
201e0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
201f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
20200 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
20210 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
20220 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
20230 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
20240 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20250 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
20260 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
20270 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  esult.**.** ^(Th
20280 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
20290 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
202a0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
202b0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
202c0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
202d0 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
202e0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
202f0 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
20300 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
20310 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
20320 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
20330 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
20340 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
20350 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
20360 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
20370 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
20380 73 20 72 65 74 75 72 6e 65 64 2e 29 20 20 5e 49  s returned.)  ^I
20390 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
203a0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
203b0 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72  et is an.** expr
203c0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
203d0 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20  ry, then a NULL 
203e0 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
203f0 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ned..** ^The ret
20400 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
20410 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63  always UTF-8 enc
20420 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f  oded..**.** ^(Fo
20430 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e  r example, given
20440 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
20450 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41  hema:.**.** CREA
20460 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56  TE TABLE t1(c1 V
20470 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61  ARIANT);.**.** a
20480 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  nd the following
20490 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
204a0 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a   compiled:.**.**
204b0 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20   SELECT c1 + 1, 
204c0 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a  c1 FROM t1;.**.*
204d0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  * this routine w
204e0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
204f0 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22  string "VARIANT"
20500 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20   for the second 
20510 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e  result.** column
20520 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e   (i==1), and a N
20530 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ULL pointer for 
20540 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74  the first result
20550 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29   column (i==0).)
20560 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ^.**.** ^SQLite 
20570 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e  uses dynamic run
20580 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e  -time typing.  ^
20590 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20  So just because 
205a0 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64  a column.** is d
205b0 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61  eclared to conta
205c0 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  in a particular 
205d0 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65  type does not me
205e0 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64  an that the.** d
205f0 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68  ata stored in th
20600 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20  at column is of 
20610 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
20620 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  e.  SQLite is.**
20630 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c   strongly typed,
20640 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20   but the typing 
20650 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73  is dynamic not s
20660 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a  tatic.  ^Type.**
20670 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77   is associated w
20680 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76  ith individual v
20690 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20  alues, not with 
206a0 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a  the containers.*
206b0 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74  * used to hold t
206c0 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a  hose values..*/.
206d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
206e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
206f0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
20700 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
20710 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
20720 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
20730 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
20740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20750 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
20760 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
20770 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
20780 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20790 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
207a0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
207b0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
207c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
207d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
207e0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
207f0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
20800 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
20810 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
20820 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20830 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
20840 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
20850 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
20860 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
20870 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
20880 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
20890 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
208a0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
208b0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
208c0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
208d0 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
208e0 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
208f0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
20900 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
20910 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
20920 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
20930 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
20940 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
20950 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
20960 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
20970 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
20980 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
20990 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
209a0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
209b0 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
209c0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
209d0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
209e0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
209f0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
20a00 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
20a10 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
20a20 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
20a30 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
20a40 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
20a50 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
20a60 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
20a70 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
20a80 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
20a90 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
20aa0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
20ab0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
20ac0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
20ad0 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
20ae0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
20af0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
20b00 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
20b10 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
20b20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
20b30 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
20b40 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
20b50 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
20b60 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
20b70 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
20b80 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
20b90 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
20ba0 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
20bb0 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
20bc0 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
20bd0 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
20be0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
20bf0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
20c00 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
20c10 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
20c20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
20c30 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
20c40 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a  occurs within a.
20c50 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
20c60 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
20c70 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
20c80 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
20c90 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
20ca0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
20cb0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
20cc0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
20cd0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
20ce0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
20cf0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
20d00 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
20d10 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
20d20 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
20d30 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
20d40 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
20d50 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
20d60 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
20d70 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
20d80 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
20d90 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
20da0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
20db0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
20dc0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
20dd0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
20de0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
20df0 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
20e00 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
20e10 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
20e20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
20e30 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
20e40 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
20e50 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
20e60 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
20e70 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
20e80 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
20e90 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
20ea0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
20eb0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
20ec0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
20ed0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
20ee0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
20ef0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
20f00 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
20f10 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
20f20 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
20f30 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
20f40 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
20f50 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
20f60 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
20f70 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
20f80 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
20f90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
20fa0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
20fb0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
20fc0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
20fd0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
20fe0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
20ff0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
21000 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
21010 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
21020 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
21030 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
21040 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
21050 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
21060 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
21070 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
21080 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
21090 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
210a0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
210b0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
210c0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
210d0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
210e0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
210f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
21100 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
21110 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
21120 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
21130 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
21140 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
21150 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
21160 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
21170 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
21180 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
21190 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
211a0 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
211b0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
211c0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
211d0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
211e0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
211f0 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
21200 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
21210 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
21220 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
21230 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
21240 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
21250 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
21260 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
21270 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
21280 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
21290 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
212a0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
212b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
212c0 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
212d0 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
212e0 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
212f0 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
21300 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
21310 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
21320 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
21330 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
21340 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
21350 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
21360 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
21370 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
21380 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
21390 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
213a0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
213b0 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
213c0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
213d0 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
213e0 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
213f0 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
21400 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
21410 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
21420 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
21430 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
21440 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
21450 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
21460 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
21470 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21480 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
21490 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
214a0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
214b0 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
214c0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
214d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
214e0 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
214f0 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
21500 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
21510 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
21520 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
21530 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
21540 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
21550 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
21560 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
21570 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  mended..*/.int s
21580 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
21590 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
215a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
215b0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
215c0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
215d0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74 68  *.** ^Returns th
215e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 76 61 6c 75  e number of valu
215f0 65 73 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  es in the curren
21600 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
21610 75 6c 74 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20  ult set..*/.int 
21620 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
21630 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
21640 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
21650 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
21660 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
21670 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
21680 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 7b  ITE_TEXT.**.** {
21690 48 31 30 32 36 36 7d 20 45 76 65 72 79 20 76 61  H10266} Every va
216a0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
216b0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
216c0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
216d0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
216e0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
216f0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
21700 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
21710 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
21720 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
21730 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
21740 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
21750 0a 2a 2a 20 3c 2f 75 6c 3e 20 7b 45 4e 44 7d 0a  .** </ul> {END}.
21760 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
21770 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
21780 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
21790 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
217a0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
217b0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
217c0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
217d0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
217e0 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
217f0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
21800 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
21810 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
21820 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
21830 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
21840 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
21850 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
21860 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
21870 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
21880 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
21890 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
218a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
218b0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
218c0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
218d0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
218e0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
218f0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
21900 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
21910 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
21920 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
21930 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
21940 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
21950 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
21960 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
21970 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
21980 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
21990 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
219a0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
219b0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
219c0 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
219d0 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e   set" interface.
219e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
219f0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
21a00 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
21a10 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
21a20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
21a30 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
21a40 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
21a50 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
21a60 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
21a70 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
21a80 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
21a90 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
21aa0 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
21ab0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
21ac0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
21ad0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
21ae0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21af0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
21b00 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
21b10 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
21b20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
21b30 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
21b40 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
21b50 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
21b60 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
21b70 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
21b80 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
21b90 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
21ba0 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
21bb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
21bc0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
21bd0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
21be0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
21bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
21c00 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
21c10 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
21c20 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
21c30 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
21c40 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
21c50 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
21c60 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
21c70 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
21c80 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
21c90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
21ca0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
21cb0 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
21cc0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
21cd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
21ce0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
21cf0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
21d00 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
21d10 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
21d20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
21d30 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
21d40 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
21d50 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
21d60 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
21d70 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
21d80 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
21d90 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
21da0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
21db0 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
21dc0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
21dd0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
21de0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
21df0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
21e00 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
21e10 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
21e20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21e30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
21e40 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
21e50 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
21e60 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
21e70 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
21e80 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
21e90 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
21ea0 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
21eb0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
21ec0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
21ed0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
21ee0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
21ef0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
21f00 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
21f10 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
21f20 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
21f30 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
21f40 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
21f50 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
21f60 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
21f70 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
21f80 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
21f90 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
21fa0 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
21fb0 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
21fc0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
21fd0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
21fe0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
21ff0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
22000 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
22010 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
22020 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
22030 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
22040 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
22050 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
22060 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
22070 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
22080 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22090 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
220a0 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
220b0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
220c0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
220d0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
220e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
220f0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
22100 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
22110 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
22120 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
22130 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
22140 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
22150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
22160 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
22170 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
22180 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
22190 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
221a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
221b0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
221c0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
221d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
221e0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
221f0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
22200 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
22210 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
22220 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
22230 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
22240 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
22250 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
22260 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
22270 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
22280 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
22290 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
222a0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
222b0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
222c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
222d0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
222e0 67 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  g..** ^The value
222f0 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e   returned does n
22300 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
22310 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 61  ero terminator a
22320 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
22330 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
22340 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
22350 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
22360 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
22370 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
22380 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
22390 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
223a0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
223b0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
223c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
223d0 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
223e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
223f0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
22400 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
22410 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e  ways zero termin
22420 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
22430 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
22440 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22450 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
22460 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
22470 20 61 6e 20 61 72 62 69 74 72 61 72 79 0a 2a 2a   an arbitrary.**
22480 20 70 6f 69 6e 74 65 72 2c 20 70 6f 73 73 69 62   pointer, possib
22490 6c 79 20 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70  ly even a NULL p
224a0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
224b0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
224c0 6e 5f 62 79 74 65 73 31 36 28 29 20 72 6f 75 74  n_bytes16() rout
224d0 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
224e0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
224f0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 62 75 74 20  _bytes().** but 
22500 6c 65 61 76 65 73 20 74 68 65 20 72 65 73 75 6c  leaves the resul
22510 74 20 69 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e  t in UTF-16 in n
22520 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
22530 20 69 6e 73 74 65 61 64 20 6f 66 20 55 54 46 2d   instead of UTF-
22540 38 2e 0a 2a 2a 20 5e 54 68 65 20 7a 65 72 6f 20  8..** ^The zero 
22550 74 65 72 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f  terminator is no
22560 74 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  t included in th
22570 69 73 20 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20  is count..**.** 
22580 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
22590 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
225a0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
225b0 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
225c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
225d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
225e0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
225f0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
22600 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
22610 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
22620 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
22630 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
22640 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
22650 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
22660 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
22670 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
22680 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
22690 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
226a0 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
226b0 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
226c0 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
226d0 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
226e0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
226f0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
22700 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
22710 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
22720 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
22730 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
22740 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
22750 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
22760 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
22770 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
22780 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
22790 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
227a0 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
227b0 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
227c0 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
227d0 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
227e0 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
227f0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
22800 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
22810 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
22820 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
22830 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
22840 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
22850 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
22860 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
22870 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
22880 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
22890 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
228a0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
228b0 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
228c0 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
228d0 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
228e0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
228f0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
22900 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
22910 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
22920 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
22930 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
22940 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
22950 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
22960 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
22970 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
22980 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
22990 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
229a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
229b0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
229c0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
229d0 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
229e0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
229f0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
22a00 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
22a10 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
22a20 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
22a30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
22a40 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
22a50 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
22a60 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
22a70 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
22a80 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
22a90 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
22aa0 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
22ab0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
22ac0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
22ad0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
22ae0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
22af0 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
22b00 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
22b10 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
22b20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
22b30 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
22b40 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
22b50 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
22b60 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
22b70 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
22b80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
22b90 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
22ba0 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
22bb0 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
22bc0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
22bd0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
22be0 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
22bf0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
22c00 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
22c10 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
22c20 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
22c30 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
22c40 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
22c50 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
22c60 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
22c70 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
22c80 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
22c90 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
22ca0 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
22cb0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
22cc0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
22cd0 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
22ce0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
22cf0 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
22d00 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
22d10 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te>)^.**.** The 
22d20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
22d30 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
22d40 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
22d50 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
22d60 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
22d70 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
22d80 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
22d90 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
22da0 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
22db0 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
22dc0 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
22dd0 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
22de0 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
22df0 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
22e00 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
22e10 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
22e20 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
22e30 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
22e40 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
22e50 5e 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20  ^Note that when 
22e60 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
22e70 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
22e80 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
22e90 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
22ea0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
22eb0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
22ec0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
22ed0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
22ee0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
22ef0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
22f00 64 2e 0a 2a 2a 20 5e 28 54 79 70 65 20 63 6f 6e  d..** ^(Type con
22f10 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
22f20 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
22f30 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
22f40 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
22f50 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
22f60 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
22f70 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
22f80 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
22f90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
22fa0 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
22fb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
22fc0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
22fd0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
22fe0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
22ff0 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
23000 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
23010 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
23020 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
23030 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
23040 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
23050 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
23060 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
23070 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
23080 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
23090 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
230a0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
230b0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
230c0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
230d0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
230e0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
230f0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
23100 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
23110 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
23120 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
23130 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
23140 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
23150 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
23160 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
23170 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43  </ul>)^.**.** ^C
23180 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
23190 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
231a0 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
231b0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
231c0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
231d0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
231e0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
231f0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
23200 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
23210 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
23220 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
23230 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20   points to will 
23240 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
23250 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
23260 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
23270 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
23280 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
23290 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
232a0 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
232b0 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
232c0 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
232d0 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
232e0 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
232f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  d..**.** ^(The s
23300 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
23310 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
23320 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
23330 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
23340 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
23350 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
23360 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
23370 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
23380 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
23390 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
233a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
233b0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
233c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
233d0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
233e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
233f0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
23400 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
23410 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
23420 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
23430 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
23440 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  i>.** </ul>)^.**
23450 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
23460 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
23470 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
23480 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
23490 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
234a0 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
234b0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
234c0 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
234d0 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
234e0 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
234f0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
23500 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
23510 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
23520 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23530 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
23540 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
23550 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
23560 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
23570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
23580 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
23590 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
235a0 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
235b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
235c0 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
235d0 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
235e0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
235f0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
23600 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
23610 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
23620 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
23630 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
23640 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
23650 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
23660 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
23670 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
23680 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
23690 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
236a0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
236b0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
236c0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
236d0 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
236e0 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
236f0 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
23700 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
23710 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
23720 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
23730 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
23740 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
23750 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23760 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
23770 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
23780 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
23790 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
237a0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
237b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
237c0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
237d0 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
237e0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
237f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
23800 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
23810 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
23820 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
23830 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
23840 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
23850 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
23860 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
23870 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
23880 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
23890 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
238a0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
238b0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
238c0 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
238d0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
238e0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
238f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
23900 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
23910 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
23920 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
23930 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
23940 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23950 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
23960 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
23970 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
23980 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
23990 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
239a0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
239b0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
239c0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
239d0 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
239e0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
239f0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
23a00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
23a10 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
23a20 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
23a30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
23a40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
23a50 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
23a60 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
23a70 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
23a80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
23a90 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
23aa0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
23ab0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
23ac0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
23ad0 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
23ae0 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
23af0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
23b00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23b10 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
23b20 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
23b30 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
23b40 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
23b50 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
23b60 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
23b70 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
23b80 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
23b90 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
23ba0 77 61 73 20 65 78 65 63 75 74 65 64 20 73 75 63  was executed suc
23bb0 63 65 73 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74  cessfully or not
23bc0 20 65 78 65 63 75 74 65 64 20 61 74 20 61 6c 6c   executed at all
23bd0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45  , then.** SQLITE
23be0 5f 4f 4b 20 69 73 20 72 65 74 75 72 6e 65 64 2e  _OK is returned.
23bf0 20 5e 49 66 20 65 78 65 63 75 74 69 6f 6e 20 6f   ^If execution o
23c00 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
23c10 66 61 69 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a  failed then an.*
23c20 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  * [error code] o
23c30 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
23c40 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
23c50 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ned..**.** ^This
23c60 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
23c70 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
23c80 69 6e 74 20 64 75 72 69 6e 67 20 74 68 65 20 65  int during the e
23c90 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a  xecution of the.
23ca0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
23cb0 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 66 20 74 68  tement].  ^If th
23cc0 65 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  e virtual machin
23cd0 65 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d  e has not.** com
23ce0 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
23cf0 20 77 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   when this routi
23d00 6e 65 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  ne is called, th
23d10 61 74 20 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e  at is like.** en
23d20 63 6f 75 6e 74 65 72 69 6e 67 20 61 6e 20 65 72  countering an er
23d30 72 6f 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ror or an [sqlit
23d40 65 33 5f 69 6e 74 65 72 72 75 70 74 20 7c 20 69  e3_interrupt | i
23d50 6e 74 65 72 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49  nterrupt]..** ^I
23d60 6e 63 6f 6d 70 6c 65 74 65 20 75 70 64 61 74 65  ncomplete update
23d70 73 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20  s may be rolled 
23d80 62 61 63 6b 20 61 6e 64 20 74 72 61 6e 73 61 63  back and transac
23d90 74 69 6f 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a  tions canceled,.
23da0 2a 2a 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ** depending on 
23db0 74 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  the circumstance
23dc0 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65  s, and the.** [e
23dd0 72 72 6f 72 20 63 6f 64 65 5d 20 72 65 74 75 72  rror code] retur
23de0 6e 65 64 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c  ned will be [SQL
23df0 49 54 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69  ITE_ABORT]..*/.i
23e00 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  nt sqlite3_final
23e10 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ize(sqlite3_stmt
23e20 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
23e30 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
23e40 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
23e50 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
23e60 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
23e70 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
23e80 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
23e90 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
23ea0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
23eb0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
23ec0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
23ed0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
23ee0 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
23ef0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
23f00 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
23f10 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
23f20 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
23f30 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
23f40 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
23f50 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
23f60 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
23f70 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
23f80 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
23f90 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
23fa0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
23fb0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
23fc0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
23fd0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
23fe0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23ff0 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
24000 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
24010 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
24020 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
24030 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
24040 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
24050 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
24060 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24070 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
24080 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
24090 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
240a0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
240b0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
240c0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
240d0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
240e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
240f0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
24100 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
24110 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
24120 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
24130 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
24140 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
24150 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
24160 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
24170 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
24180 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
24190 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
241a0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
241b0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
241c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
241d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
241e0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
241f0 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
24200 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
24210 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
24220 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
24230 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
24240 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
24250 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
24260 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
24270 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
24280 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
24290 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
242a0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
242b0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
242c0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
242d0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
242e0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
242f0 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
24300 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
24310 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
24320 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions}.**.** ^The
24330 73 65 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  se two functions
24340 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
24350 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
24360 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
24370 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
24380 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
24390 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
243a0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
243b0 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
243c0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
243d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
243e0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
243f0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
24400 65 20 62 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a  e between the.**
24410 20 74 77 6f 20 69 73 20 74 68 61 74 20 74 68 65   two is that the
24420 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
24430 72 2c 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r, the name of t
24440 68 65 20 28 73 63 61 6c 61 72 29 20 66 75 6e 63  he (scalar) func
24450 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
24460 67 61 74 65 2c 20 69 73 20 65 6e 63 6f 64 65 64  gate, is encoded
24470 20 69 6e 20 55 54 46 2d 38 20 66 6f 72 20 73 71   in UTF-8 for sq
24480 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
24490 63 74 69 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d  ction() and UTF-
244a0 31 36 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  16.** for sqlite
244b0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
244c0 6e 31 36 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  n16()..**.** The
244d0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
244e0 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
244f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
24500 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
24510 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
24520 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
24530 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 61 6d  a single program
24540 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
24550 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
24560 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 6e 74 65 72  connection inter
24570 6e 61 6c 6c 79 2c 20 74 68 65 6e 20 53 51 4c 20  nally, then SQL 
24580 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
24590 65 20 61 64 64 65 64 20 69 6e 64 69 76 69 64 75  e added individu
245a0 61 6c 6c 79 20 74 6f 0a 2a 2a 20 65 61 63 68 20  ally to.** each 
245b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
245c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ion..**.** The s
245d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
245e0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
245f0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
24600 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
24610 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
24620 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
24630 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
24640 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 2c  ed to 255 bytes,
24650 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a 2a   exclusive of.**
24660 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
24670 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61 74  ator.  Note that
24680 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74 68   the name length
24690 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79 74   limit is in byt
246a0 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72 61  es, not.** chara
246b0 63 74 65 72 73 2e 20 20 5e 41 6e 79 20 61 74 74  cters.  ^Any att
246c0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
246d0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
246e0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
246f0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
24700 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62 65  SQLITE_ERROR] be
24710 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
24720 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
24730 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
24740 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
24750 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
24760 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
24770 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
24780 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
24790 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
247a0 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
247b0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
247c0 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
247d0 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
247e0 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
247f0 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
24800 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
24810 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
24820 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
24830 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
24840 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
24850 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
24860 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
24870 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
24880 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
24890 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
248a0 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20 70  .** The fourth p
248b0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
248c0 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
248d0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
248e0 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
248f0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
24900 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
24910 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
24920 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66 75  ers.  Any SQL fu
24930 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
24940 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20  ation should be 
24950 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
24960 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38 2c  work with UTF-8,
24970 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
24980 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
24990 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
249a0 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
249b0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
249c0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
249d0 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20  n another.  ^An 
249e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a  application may.
249f0 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
24a00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
24a10 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
24a20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
24a30 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
24a40 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
24a50 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
24a60 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
24a70 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
24a80 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  p..** ^When mult
24a90 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
24aa0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
24ab0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
24ac0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
24ad0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
24ae0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
24af0 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
24b00 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
24b10 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
24b20 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
24b30 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
24b40 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
24b50 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78  ot care what tex
24b60 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73  t.** encoding is
24b70 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
24b80 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
24b90 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54  should be [SQLIT
24ba0 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  E_ANY]..**.** ^(
24bb0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
24bc0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
24bd0 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
24be0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
24bf0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
24c00 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
24c10 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
24c20 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
24c30 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
24c40 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 76  )^.**.** The sev
24c50 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e 64  enth, eighth and
24c60 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72   ninth parameter
24c70 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
24c80 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
24c90 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
24ca0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
24cb0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
24cc0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
24cd0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
24ce0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
24cf0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
24d00 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
24d10 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
24d20 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
24d30 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
24d40 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ers should be pa
24d50 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
24d60 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
24d70 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
24d80 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
24d90 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
24da0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
24db0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
24dc0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
24dd0 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73 73  L should be pass
24de0 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
24df0 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
24e00 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
24e10 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
24e20 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f 72  e, pass NULL for
24e30 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74   all three funct
24e40 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  ion callbacks..*
24e50 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d  *.** ^It is perm
24e60 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65  itted to registe
24e70 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  r multiple imple
24e80 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
24e90 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69  e same.** functi
24ea0 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  ons with the sam
24eb0 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20  e name but with 
24ec0 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67  either differing
24ed0 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61   numbers of.** a
24ee0 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66  rguments or diff
24ef0 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20  ering preferred 
24f00 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20  text encodings. 
24f10 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
24f20 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  e.** the impleme
24f30 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73  ntation that mos
24f40 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65  t closely matche
24f50 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69  s the way in whi
24f60 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75  ch the.** SQL fu
24f70 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20  nction is used. 
24f80 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70   ^A function imp
24f90 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
24fa0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a   a non-negative.
24fb0 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65  ** nArg paramete
24fc0 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61  r is a better ma
24fd0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
24fe0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
24ff0 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67  on with.** a neg
25000 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20  ative nArg.  ^A 
25010 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
25020 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78  he preferred tex
25030 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61  t encoding.** ma
25040 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61  tches the databa
25050 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61  se encoding is a
25060 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68   better.** match
25070 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
25080 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
25090 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
250a0 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69  .  .** ^A functi
250b0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
250c0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
250d0 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31   is between UTF1
250e0 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a  6le and UTF16be.
250f0 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d  ** is a closer m
25100 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
25110 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
25120 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
25130 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e  ce is.** between
25140 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e   UTF8 and UTF16.
25150 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e  .**.** ^Built-in
25160 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
25170 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20  e overloaded by 
25180 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  new application-
25190 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
251a0 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  s..** ^The first
251b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
251c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77 69  ined function wi
251d0 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65 20  th a given name 
251e0 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a 2a  overrides all.**
251f0 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69   built-in functi
25200 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65 20  ons in the same 
25210 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25220 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20 73  tion] with the s
25230 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53 75  ame name..** ^Su
25240 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63 61  bsequent applica
25250 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
25260 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ctions of the sa
25270 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76 65  me name only ove
25280 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72 20  rride .** prior 
25290 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
252a0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ned functions th
252b0 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74 20  at are an exact 
252c0 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a 2a  match for the.**
252d0 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61 6d   number of param
252e0 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65 72  eters and prefer
252f0 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  red encoding..**
25300 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  .** ^An applicat
25310 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
25320 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
25330 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a  d to call other.
25340 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
25350 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20  aces.  However, 
25360 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20  such calls must 
25370 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65  not.** close the
25380 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25390 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a  tion nor finaliz
253a0 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70  e or reset the p
253b0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
253c0 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68  ment in which th
253d0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  e function is ru
253e0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71  nning..*/.int sq
253f0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25400 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ction(.  sqlite3
25410 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
25420 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
25430 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
25440 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
25450 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
25460 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
25470 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
25480 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
25490 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
254a0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
254b0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
254c0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
254d0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
254e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
254f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
25500 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a  ate_function16(.
25510 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
25520 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75   const void *zFu
25530 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
25540 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
25550 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
25560 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
25570 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
25580 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
25590 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
255a0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
255b0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
255c0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
255d0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
255e0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
255f0 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  text*).);../*.**
25600 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
25610 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
25620 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
25630 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
25640 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
25650 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
25660 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
25670 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
25680 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
25690 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
256a0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
256b0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
256c0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
256d0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
256e0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
256f0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
25700 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
25710 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
25720 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
25730 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
25740 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
25750 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
25760 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
25770 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
25780 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
25790 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
257a0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
257b0 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
257c0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
257d0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
257e0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
257f0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
25800 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
25810 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
25820 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
25830 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
25840 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
25850 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
25860 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
25870 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
25880 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
25890 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
258a0 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
258b0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
258c0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
258d0 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
258e0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
258f0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
25900 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
25910 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
25920 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
25930 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
25940 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
25950 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
25960 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
25970 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
25980 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
25990 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
259a0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
259b0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
259c0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
259d0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
259e0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
259f0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
25a00 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
25a10 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
25a20 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
25a30 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
25a40 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
25a50 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
25a60 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
25a70 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
25a80 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
25a90 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
25aa0 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
25ab0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
25ac0 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
25ad0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
25ae0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
25af0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
25b00 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
25b10 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
25b20 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
25b30 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
25b40 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
25b50 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
25b60 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
25b70 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
25b80 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
25b90 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
25ba0 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
25bb0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
25bc0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
25bd0 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
25be0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
25bf0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
25c00 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
25c10 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
25c20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
25c30 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
25c40 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
25c50 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
25c60 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
25c70 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
25c80 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
25c90 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
25ca0 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70 61  s..** The 4th pa
25cb0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
25cc0 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
25cd0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
25ce0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
25cf0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
25d00 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
25d10 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
25d20 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
25d30 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
25d40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
25d50 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
25d60 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
25d70 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
25d80 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
25d90 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
25da0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
25db0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
25dc0 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
25dd0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
25de0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
25df0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
25e00 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
25e10 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
25e20 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
25e30 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
25e40 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
25e50 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
25e60 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
25e70 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
25e80 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
25e90 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
25ea0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
25eb0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
25ec0 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
25ed0 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
25ee0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
25ef0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
25f00 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
25f10 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
25f20 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
25f30 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
25f40 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
25f50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
25f60 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
25f70 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
25f80 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
25f90 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
25fa0 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
25fb0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
25fc0 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
25fd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
25fe0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
25ff0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
26000 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
26010 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
26020 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
26030 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
26040 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
26050 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
26060 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
26070 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
26080 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
26090 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
260a0 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
260b0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
260c0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
260d0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
260e0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
260f0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
26100 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
26110 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
26120 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
26130 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
26140 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
26150 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
26160 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
26170 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
26180 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
26190 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
261a0 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
261b0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
261c0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
261d0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
261e0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
261f0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
26200 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
26210 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
26220 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
26230 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
26240 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
26250 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
26260 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
26270 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
26280 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
26290 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
262a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
262b0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
262c0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
262d0 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
262e0 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
262f0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
26300 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
26310 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
26320 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
26330 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
26340 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
26350 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
26360 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
26370 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
26380 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
26390 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
263a0 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
263b0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
263c0 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
263d0 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
263e0 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73  ameters..*/.cons
263f0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
26400 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
26410 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
26420 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
26430 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
26440 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
26450 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
26460 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
26470 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
26480 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
26490 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
264a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
264b0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
264c0 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
264d0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
264e0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
264f0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
26500 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
26510 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
26520 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
26530 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
26540 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
26550 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
26560 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
26570 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
26580 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
26590 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
265a0 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
265b0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
265c0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
265d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
265e0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
265f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
26600 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
26610 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
26620 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26630 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67  F: Obtain Aggreg
26640 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e  ate Function Con
26650 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65  text.**.** Imple
26660 6d 65 6e 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  mentions of aggr
26670 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
26680 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
26690 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
266a0 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
266b0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
266c0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
266d0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
266e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
266f0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
26700 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
26710 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
26720 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
26730 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
26740 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
26750 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
26760 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
26770 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
26780 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
26790 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
267a0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
267b0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
267c0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
267d0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
267e0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
267f0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
26800 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
26810 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
26820 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
26830 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
26840 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
26850 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
26860 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
26870 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
26880 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
26890 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
268a0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
268b0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
268c0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
268d0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
268e0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
268f0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
26900 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
26910 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
26920 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
26930 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
26940 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
26950 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
26960 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
26970 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
26980 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
26990 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
269a0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
269b0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
269c0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
269d0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
269e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
269f0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
26a00 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
26a10 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
26a20 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65  er if N is.** le
26a30 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
26a40 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
26a50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
26a60 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
26a70 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
26a80 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
26a90 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
26aa0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
26ab0 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
26ac0 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
26ad0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
26ae0 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
26af0 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
26b00 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
26b10 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
26b20 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
26b30 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
26b40 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
26b50 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
26b60 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
26b70 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
26b80 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
26b90 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  allocation.)^.**
26ba0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
26bb0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
26bc0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
26bd0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
26be0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
26bf0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
26c00 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
26c10 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
26c20 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
26c30 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
26c40 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
26c50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
26c60 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
26c70 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
26c80 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
26c90 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
26ca0 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
26cb0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
26cc0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
26cd0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
26ce0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
26cf0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
26d00 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
26d10 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
26d20 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
26d30 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
26d40 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
26d50 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
26d60 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
26d70 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
26d80 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
26d90 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
26da0 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
26db0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
26dc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26dd0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
26de0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26df0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
26e00 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
26e10 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
26e20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
26e30 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
26e40 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
26e50 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
26e60 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
26e70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
26e80 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
26e90 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
26ea0 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
26eb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
26ec0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
26ed0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
26ee0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
26ef0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
26f00 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
26f10 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
26f20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
26f30 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
26f40 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
26f50 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
26f60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
26f70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26f80 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
26f90 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
26fa0 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
26fb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
26fc0 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
26fd0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
26fe0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
26ff0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
27000 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27010 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
27020 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
27030 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
27040 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
27050 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
27060 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
27070 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
27080 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
27090 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
270a0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
270b0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c  function..*/.sql
270c0 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
270d0 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
270e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
270f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27100 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
27110 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
27120 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
27130 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
27140 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
27150 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
27160 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
27170 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
27180 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
27190 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
271a0 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
271b0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
271c0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
271d0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
271e0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
271f0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
27200 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
27210 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
27220 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
27230 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
27240 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
27250 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
27260 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
27270 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
27280 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
27290 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
272a0 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
272b0 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
272c0 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
272d0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
272e0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
272f0 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
27300 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
27310 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
27320 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
27330 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
27340 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
27350 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
27360 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
27370 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
27380 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
27390 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
273a0 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
273b0 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
273c0 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
273d0 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
273e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
273f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
27400 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
27410 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
27420 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
27430 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
27440 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
27450 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
27460 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
27470 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
27480 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
27490 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
274a0 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e   function. ^If n
274b0 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
274c0 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
274d0 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
274e0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
274f0 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
27500 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
27510 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
27520 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
27530 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
27540 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
27550 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
27560 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
27570 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
27580 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
27590 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
275a0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
275b0 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
275c0 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
275d0 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
275e0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
275f0 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
27600 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
27610 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
27620 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
27630 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
27640 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
27650 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
27660 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
27670 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
27680 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
27690 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
276a0 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   ^If it is not N
276b0 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
276c0 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
276d0 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
276e0 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
276f0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
27700 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
27710 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
27720 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
27730 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
27740 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
27750 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
27760 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
27770 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
27780 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
27790 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
277a0 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
277b0 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
277c0 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
277d0 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
277e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
277f0 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
27800 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  any time.  ^The 
27810 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
27820 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
27830 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
27840 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
27850 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
27860 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ropped..**.** ^(
27870 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
27880 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
27890 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
278a0 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
278b0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
278c0 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
278d0 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
278e0 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
278f0 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
27900 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
27910 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
27920 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
27930 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
27940 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
27950 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
27960 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
27970 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
27980 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
27990 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
279a0 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
279b0 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
279c0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
279d0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
279e0 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
279f0 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
27a00 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
27a10 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
27a20 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
27a30 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
27a40 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
27a50 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
27a60 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
27a70 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
27a80 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
27a90 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
27aa0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
27ab0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
27ac0 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
27ad0 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
27ae0 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
27af0 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
27b00 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
27b10 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
27b20 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
27b30 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
27b40 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
27b50 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
27b60 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
27b70 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
27b80 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
27b90 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
27ba0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
27bb0 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
27bc0 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
27bd0 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
27be0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
27bf0 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
27c00 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
27c10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
27c20 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
27c30 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
27c40 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
27c50 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
27c60 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65  lers.  See ticke
27c70 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65  t #2191..*/.type
27c80 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
27c90 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
27ca0 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
27cb0 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
27cc0 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
27cd0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
27ce0 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
27cf0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
27d00 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
27d10 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
27d20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
27d30 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
27d40 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
27d50 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ion.**.** These 
27d60 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
27d70 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
27d80 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
27d90 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
27da0 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
27db0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
27dc0 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
27dd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27de0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
27df0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27e00 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
27e10 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
27e20 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
27e30 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
27e40 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
27e50 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
27e60 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
27e70 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
27e80 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
27e90 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
27ea0 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
27eb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
27ec0 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
27ed0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
27ee0 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
27ef0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
27f00 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
27f10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
27f20 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
27f30 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
27f40 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
27f50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
27f60 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
27f70 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
27f80 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
27f90 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
27fa0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
27fb0 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
27fc0 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
27fd0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
27fe0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  hird parameter..
27ff0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28000 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
28010 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  ob() interfaces 
28020 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
28030 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
28040 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
28050 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c  ction to be a BL
28060 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
28070 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20  l zero.** bytes 
28080 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
28090 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ize, where N is 
280a0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
280b0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   2nd parameter..
280c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
280d0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
280e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
280f0 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
28100 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
28110 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
28120 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
28130 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
28140 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
28150 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
28160 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
28170 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
28180 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
28190 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
281a0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
281b0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
281c0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
281d0 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
281e0 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51  xception..** ^SQ
281f0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
28200 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
28210 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
28220 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
28230 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
28240 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
28250 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
28260 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
28270 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
28280 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72  .  ^SQLite inter
28290 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
282a0 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
282b0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
282c0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
282d0 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a   UTF-8. ^SQLite.
282e0 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
282f0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
28300 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
28310 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
28320 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
28330 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74  te order.  ^If t
28340 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
28350 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
28360 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
28370 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
28380 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
28390 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
283a0 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
283b0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
283c0 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
283d0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
283e0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
283f0 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
28400 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
28410 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
28420 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
28430 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
28440 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
28450 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
28460 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
28470 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
28480 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
28490 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
284a0 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
284b0 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73  ssage..** ^The s
284c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
284d0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
284e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
284f0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
28500 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
28510 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
28520 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
28530 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
28540 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
28550 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
28560 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
28570 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
28580 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
28590 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
285a0 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  harm..** ^The sq
285b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
285c0 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
285d0 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
285e0 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
285f0 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
28600 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
28610 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
28620 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61  ction.  ^By defa
28630 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
28640 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
28650 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73  _ERROR.  ^A subs
28660 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
28670 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
28680 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
28690 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
286a0 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
286b0 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
286c0 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
286d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
286e0 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
286f0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
28700 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
28710 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
28720 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
28730 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
28740 74 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  to long to repre
28750 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
28760 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28770 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
28780 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
28790 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
287a0 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
287b0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
287c0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
287d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
287e0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
287f0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
28800 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
28810 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
28820 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
28830 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
28840 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
28850 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
28860 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
28870 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
28880 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
28890 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
288a0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
288b0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
288c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
288d0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
288e0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
288f0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
28900 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
28910 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
28920 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
28930 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
28940 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
28950 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
28960 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
28970 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
28980 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
28990 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
289a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
289b0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
289c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
289d0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
289e0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
289f0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
28a00 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
28a10 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
28a20 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
28a30 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
28a40 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
28a50 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
28a60 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
28a70 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
28a80 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
28a90 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
28aa0 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
28ab0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
28ac0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
28ad0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
28ae0 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ely..** ^SQLite 
28af0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
28b00 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
28b10 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
28b20 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
28b30 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
28b40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
28b50 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
28b60 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
28b70 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
28b80 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
28b90 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
28ba0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
28bb0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
28bc0 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
28bd0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
28be0 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
28bf0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
28c00 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
28c10 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
28c20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
28c30 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
28c40 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
28c50 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
28c60 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
28c70 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
28c80 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
28c90 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
28ca0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
28cb0 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
28cc0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
28cd0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
28ce0 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
28cf0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
28d00 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
28d10 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
28d20 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
28d30 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
28d40 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
28d50 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
28d60 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
28d70 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
28d80 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
28d90 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
28da0 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
28db0 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
28dc0 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
28dd0 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
28de0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
28df0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
28e00 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
28e10 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
28e20 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
28e30 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
28e40 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
28e50 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
28e60 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
28e70 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
28e80 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
28e90 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
28ea0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
28eb0 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
28ec0 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
28ed0 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
28ee0 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
28ef0 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
28f00 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
28f10 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
28f20 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
28f30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
28f40 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
28f50 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
28f60 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
28f70 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
28f80 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
28f90 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
28fa0 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
28fb0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
28fc0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
28fd0 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
28fe0 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
28ff0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
29000 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
29010 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
29020 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29030 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
29040 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
29050 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
29060 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
29070 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
29080 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
29090 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
290a0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
290b0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
290c0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
290d0 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
290e0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
290f0 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
29100 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
29110 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
29120 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
29130 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
29140 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
29150 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
29160 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
29170 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
29180 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
29190 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
291a0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
291b0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
291c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
291d0 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
291e0 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
291f0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
29200 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
29210 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
29220 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
29230 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
29240 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
29250 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
29260 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
29270 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
29280 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
29290 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
292a0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
292b0 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
292c0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
292d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
292e0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
292f0 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
29300 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
29310 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
29320 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
29330 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
29340 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29350 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
29360 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
29370 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
29380 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
29390 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
293a0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
293b0 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
293c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
293d0 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
293e0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
293f0 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
29400 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
29410 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
29420 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
29430 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
29440 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
29450 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
29460 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29470 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
29480 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
29490 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
294a0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
294b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
294c0 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
294d0 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
294e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
294f0 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
29500 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
29510 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
29520 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
29530 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
29540 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
29550 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
29560 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
29570 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
29580 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
29590 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
295a0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
295b0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
295c0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
295d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
295e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
295f0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
29600 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
29610 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
29620 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
29630 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29640 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
29650 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
29660 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
29670 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
29680 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
29690 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
296a0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
296b0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
296c0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
296d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
296e0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
296f0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
29700 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
29710 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29720 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
29730 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
29740 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
29750 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
29760 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
29770 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
29780 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
29790 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65 0a 2a  quences to the.*
297a0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
297b0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
297c0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
297d0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
297e0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
297f0 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  new collation se
29800 71 75 65 6e 63 65 20 69 73 20 73 70 65 63 69 66  quence is specif
29810 69 65 64 20 61 73 20 61 20 55 54 46 2d 38 20 73  ied as a UTF-8 s
29820 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c  tring.** for sql
29830 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
29840 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69  ation() and sqli
29850 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
29860 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64  tion_v2().** and
29870 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
29880 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
29890 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
298a0 29 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73 65 73  ). ^In all cases
298b0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69 73 20  .** the name is 
298c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
298d0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
298e0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
298f0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
29900 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  t may be one of 
29910 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20 5b 53  the constants [S
29920 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
29930 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
29940 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
29950 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16BE], indicatin
29960 67 20 74 68 61 74 20 74 68 65 20 75 73 65 72 2d  g that the user-
29970 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f 75 74  supplied.** rout
29980 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f 20 62  ine expects to b
29990 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74 65 72  e passed pointer
299a0 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65 6e 63  s to strings enc
299b0 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
299c0 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
299d0 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le-endian, or UT
299e0 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61 6e 2c  F-16 big-endian,
299f0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 5e   respectively. ^
29a00 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61 72 67  The.** third arg
29a10 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c 73 6f  ument might also
29a20 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   be [SQLITE_UTF1
29a30 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  6] to indicate t
29a40 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e 65 0a  hat the routine.
29a50 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69 6e 74  ** expects point
29a60 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d 31 36  ers to be UTF-16
29a70 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
29a80 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
29a90 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61 72 67  r, or the.** arg
29aa0 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b 53 51  ument can be [SQ
29ab0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
29ac0 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20 74 68  ED] if the.** th
29ad0 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65 63 74  e routine expect
29ae0 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 31 36  s pointers to 16
29af0 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67 6e 65  -bit word aligne
29b00 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f 66 20  d strings.** of 
29b10 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
29b20 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
29b30 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
29b40 20 74 6f 20 74 68 65 20 75 73 65 72 20 73 75 70   to the user sup
29b50 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20 6d 75  plied routine mu
29b60 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20  st be passed as 
29b70 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61 72 67  the fifth.** arg
29b80 75 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74 20 69  ument.  ^If it i
29b90 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69 73 20  s NULL, this is 
29ba0 74 68 65 20 73 61 6d 65 20 61 73 20 64 65 6c 65  the same as dele
29bb0 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61 74 69  ting the collati
29bc0 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 28  on.** sequence (
29bd0 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  so that SQLite c
29be0 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20 61 6e  annot call it an
29bf0 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61 63 68  ymore)..** ^Each
29c00 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c 69 63   time the applic
29c10 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 66  ation supplied f
29c20 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
29c30 65 64 2c 20 69 74 20 69 73 20 70 61 73 73 65 64  ed, it is passed
29c40 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72 73 74  .** as its first
29c50 20 70 61 72 61 6d 65 74 65 72 20 61 20 63 6f 70   parameter a cop
29c60 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
29c70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
29c80 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rth argument.** 
29c90 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
29ca0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 6f 72  e_collation() or
29cb0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
29cc0 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
29cd0 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61 69 6e  *.** ^The remain
29ce0 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ing arguments to
29cf0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29d00 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e  -supplied routin
29d10 65 20 61 72 65 20 74 77 6f 20 73 74 72 69 6e 67  e are two string
29d20 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70 72 65  s,.** each repre
29d30 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c 65 6e  sented by a (len
29d40 67 74 68 2c 20 64 61 74 61 29 20 70 61 69 72 20  gth, data) pair 
29d50 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e 20 74  and encoded in t
29d60 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 74  he encoding.** t
29d70 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 61  hat was passed a
29d80 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  s the third argu
29d90 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20 63 6f  ment when the co
29da0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
29db0 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74 65 72   was.** register
29dc0 65 64 2e 20 7b 45 4e 44 7d 20 20 54 68 65 20 61  ed. {END}  The a
29dd0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
29de0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75  ed collation rou
29df0 74 69 6e 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  tine should.** r
29e00 65 74 75 72 6e 20 6e 65 67 61 74 69 76 65 2c 20  eturn negative, 
29e10 7a 65 72 6f 20 6f 72 20 70 6f 73 69 74 69 76 65  zero or positive
29e20 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74   if the first st
29e30 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61  ring is less tha
29e40 6e 2c 0a 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20  n,.** equal to, 
29e50 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
29e60 74 68 65 20 73 65 63 6f 6e 64 20 73 74 72 69 6e  the second strin
29e70 67 2e 20 69 2e 65 2e 20 28 53 54 52 49 4e 47 31  g. i.e. (STRING1
29e80 20 2d 20 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a   - STRING2)..**.
29e90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29ea0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
29eb0 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
29ec0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
29ed0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65  collation().** e
29ee0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 74 61  xcept that it ta
29ef0 6b 65 73 20 61 6e 20 65 78 74 72 61 20 61 72 67  kes an extra arg
29f00 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
29f10 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 0a   destructor for.
29f20 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  ** the collation
29f30 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
29f40 6f 72 20 69 73 20 63 61 6c 6c 65 64 20 77 68 65  or is called whe
29f50 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  n the collation 
29f60 69 73 0a 2a 2a 20 64 65 73 74 72 6f 79 65 64 20  is.** destroyed 
29f70 61 6e 64 20 69 73 20 70 61 73 73 65 64 20 61 20  and is passed a 
29f80 63 6f 70 79 20 6f 66 20 74 68 65 20 66 6f 75 72  copy of the four
29f90 74 68 20 70 61 72 61 6d 65 74 65 72 20 76 6f 69  th parameter voi
29fa0 64 2a 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66  d* pointer.** of
29fb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65   the sqlite3_cre
29fc0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
29fd0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
29fe0 6e 73 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  ns are destroyed
29ff0 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f   when they are o
2a000 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74  verridden by lat
2a010 65 72 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a  er calls to the.
2a020 2a 2a 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65  ** collation cre
2a030 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20  ation functions 
2a040 6f 72 20 77 68 65 6e 20 74 68 65 20 5b 64 61 74  or when the [dat
2a050 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2a060 5d 20 69 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75  ] is closed.** u
2a070 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c  sing [sqlite3_cl
2a080 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  ose()]..**.** Se
2a090 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65  e also:  [sqlite
2a0a0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2a0b0 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ed()] and [sqlit
2a0c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2a0d0 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  ded16()]..*/.int
2a0e0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2a0f0 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c  collation(.  sql
2a100 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
2a110 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
2a120 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
2a130 20 76 6f 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78   void*,.  int(*x
2a140 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
2a150 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
2a160 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
2a170 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2a180 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2a190 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  v2(.  sqlite3*, 
2a1a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2a1b0 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65  Name, .  int eTe
2a1c0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c  xtRep, .  void*,
2a1d0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
2a1e0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
2a1f0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
2a200 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64  t void*),.  void
2a210 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
2a220 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
2a230 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2a240 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a  on16(.  sqlite3*
2a250 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  , .  const void 
2a260 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54  *zName,.  int eT
2a270 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a  extRep, .  void*
2a280 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
2a290 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
2a2a0 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
2a2b0 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
2a2c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2a2d0 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
2a2e0 61 6c 6c 62 61 63 6b 73 20 7b 48 31 36 37 30 30  allbacks {H16700
2a2f0 7d 20 3c 53 32 30 33 30 30 3e 0a 2a 2a 0a 2a 2a  } <S20300>.**.**
2a300 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
2a310 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
2a320 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
2a330 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
2a340 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
2a350 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
2a360 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2a370 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
2a380 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
2a390 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2a3a0 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 63 61 6c  ction] to be cal
2a3b0 6c 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  led whenever an 
2a3c0 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
2a3d0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
2a3e0 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
2a3f0 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  ** ^If the funct
2a400 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
2a410 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
2a420 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2a430 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
2a440 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
2a450 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
2a460 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
2a470 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
2a480 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
2a490 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20  d in UTF-8. ^If 
2a4a0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2a4b0 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
2a4c0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d  used,.** the nam
2a4d0 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73  es are passed as
2a4e0 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
2a4f0 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
2a500 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  rder..** ^A call
2a510 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
2a520 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 61 6e 79  ion replaces any
2a530 20 65 78 69 73 74 69 6e 67 20 63 61 6c 6c 62 61   existing callba
2a540 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e  ck..**.** ^(When
2a550 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
2a560 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
2a570 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
2a580 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
2a590 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
2a5a0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2a5b0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2a5c0 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
2a5d0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2a5e0 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
2a5f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2a600 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
2a610 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
2a620 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2a630 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
2a640 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
2a650 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
2a660 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2a670 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
2a680 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
2a690 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
2a6a0 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
2a6b0 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
2a6c0 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
2a6d0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
2a6e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2a6f0 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
2a700 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
2a710 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  )^.**.** The cal
2a720 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
2a730 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
2a740 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
2a750 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
2a760 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a770 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
2a780 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2a790 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ation16()], or.*
2a7a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2a7b0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2a7c0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2a7d0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2a7e0 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
2a7f0 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
2a800 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2a810 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
2a820 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
2a830 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2a840 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2a850 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2a860 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
2a870 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
2a880 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
2a890 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
2a8a0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2a8b0 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79  key for an encry
2a8c0 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20  pted database.  
2a8d0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f  This routine sho
2a8e0 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64  uld be.** called
2a8f0 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c   right after sql
2a900 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a  ite3_open()..**.
2a910 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
2a920 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
2a930 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
2a940 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
2a950 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
2a960 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
2a970 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c  lite3_key(.  sql
2a980 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2a990 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2a9a0 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
2a9b0 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
2a9c0 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
2a9d0 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65   nKey     /* The
2a9e0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
2a9f0 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79  * Change the key
2aa00 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61   on an open data
2aa10 62 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75  base.  If the cu
2aa20 72 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69  rrent database i
2aa30 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74  s not.** encrypt
2aa40 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ed, this routine
2aa50 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74   will encrypt it
2aa60 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72  .  If pNew==0 or
2aa70 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a   nNew==0, the.**
2aa80 20 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63   database is dec
2aa90 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  rypted..**.** Th
2aaa0 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d  e code to implem
2aab0 65 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20  ent this API is 
2aac0 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  not available in
2aad0 20 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65   the public rele
2aae0 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ase.** of SQLite
2aaf0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ab00 5f 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65  _rekey(.  sqlite
2ab10 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2ab20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2ab30 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
2ab40 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  ed */.  const vo
2ab50 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b  id *pKey, int nK
2ab60 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65  ey     /* The ne
2ab70 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  w key */.);../*.
2ab80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73  ** CAPI3REF: Sus
2ab90 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46  pend Execution F
2aba0 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a  or A Short Time.
2abb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2abc0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
2abd0 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
2abe0 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
2abf0 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
2ac00 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
2ac10 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
2ac20 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
2ac30 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
2ac40 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ameter..**.** ^I
2ac50 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
2ac60 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
2ac70 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
2ac80 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
2ac90 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
2aca0 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
2acb0 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
2acc0 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
2acd0 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
2ace0 65 63 6f 6e 64 2e 20 5e 54 68 65 20 6e 75 6d 62  econd. ^The numb
2acf0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
2ad00 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75  ds of sleep actu
2ad10 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65  ally.** requeste
2ad20 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61  d from the opera
2ad30 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72  ting system is r
2ad40 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2ad50 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74  SQLite implement
2ad60 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  s this interface
2ad70 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20   by calling the 
2ad80 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68  xSleep().** meth
2ad90 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
2ada0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
2adb0 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 69 6e 74 20 73  object..*/.int s
2adc0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
2add0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ade0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
2adf0 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
2ae00 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a  emporary Files.*
2ae10 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 67 6c  *.** ^If this gl
2ae20 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
2ae30 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
2ae40 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
2ae50 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
2ae60 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
2ae70 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
2ae80 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61  then all tempora
2ae90 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61  ry files.** crea
2aea0 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68  ted by SQLite wh
2aeb0 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
2aec0 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  -in [sqlite3_vfs
2aed0 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20   | VFS].** will 
2aee0 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61  be placed in tha
2aef0 74 20 64 69 72 65 63 74 6f 72 79 2e 20 20 5e 49  t directory.  ^I
2af00 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
2af10 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
2af20 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
2af30 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
2af40 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
2af50 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
2af60 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
2af70 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
2af80 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
2af90 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
2afa0 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
2afb0 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
2afc0 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
2afd0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
2afe0 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
2aff0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
2b000 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
2b010 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
2b020 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
2b030 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
2b040 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
2b050 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
2b060 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
2b070 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
2b080 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
2b090 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
2b0a0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
2b0b0 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
2b0c0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
2b0d0 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
2b0e0 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
2b0f0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
2b100 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
2b110 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
2b120 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
2b130 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
2b140 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
2b150 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
2b160 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
2b170 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
2b180 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
2b190 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2b1a0 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
2b1b0 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
2b1c0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
2b1d0 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
2b1e0 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
2b1f0 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
2b200 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
2b210 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
2b220 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
2b230 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
2b240 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
2b250 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
2b260 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
2b270 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
2b280 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
2b290 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
2b2a0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
2b2b0 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
2b2c0 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
2b2d0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
2b2e0 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
2b2f0 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
2b300 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2b310 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
2b320 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
2b330 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
2b340 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
2b350 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
2b360 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51  e avoided..*/.SQ
2b370 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
2b380 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   *sqlite3_temp_d
2b390 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
2b3a0 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
2b3b0 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20  For Auto-Commit 
2b3c0 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  Mode.** KEYWORDS
2b3d0 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
2b3e0 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  de}.**.** ^The s
2b3f0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
2b400 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
2b410 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
2b420 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
2b430 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
2b440 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2b450 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
2b460 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
2b470 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2b480 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f    ^Autocommit mo
2b490 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  de is on by defa
2b4a0 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ult..** ^Autocom
2b4b0 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61  mit mode is disa
2b4c0 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e  bled by a [BEGIN
2b4d0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
2b4e0 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
2b4f0 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62   is re-enabled b
2b500 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  y a [COMMIT] or 
2b510 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a  [ROLLBACK]..**.*
2b520 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e  * If certain kin
2b530 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63  ds of errors occ
2b540 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e  ur on a statemen
2b550 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69  t within a multi
2b560 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72  -statement.** tr
2b570 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72  ansaction (error
2b580 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c  s including [SQL
2b590 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_FULL], [SQLI
2b5a0 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53  TE_IOERR],.** [S
2b5b0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53  QLITE_NOMEM], [S
2b5c0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64  QLITE_BUSY], and
2b5d0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
2b5e0 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a  PT]) then the.**
2b5f0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67   transaction mig
2b600 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ht be rolled bac
2b610 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
2b620 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74    The only way t
2b630 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68  o.** find out wh
2b640 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74  ether SQLite aut
2b650 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
2b660 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  d back the trans
2b670 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20  action after.** 
2b680 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75  an error is to u
2b690 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  se this function
2b6a0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68  ..**.** If anoth
2b6b0 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65  er thread change
2b6c0 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74  s the autocommit
2b6d0 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64   status of the d
2b6e0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
2b6f0 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73  ction while this
2b700 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e   routine is runn
2b710 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
2b720 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73  turn value.** is
2b730 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69   undefined..*/.i
2b740 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  nt sqlite3_get_a
2b750 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65  utocommit(sqlite
2b760 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
2b770 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44  3REF: Find The D
2b780 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f  atabase Handle O
2b790 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
2b7a0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  tement.**.** ^Th
2b7b0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e  e sqlite3_db_han
2b7c0 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72 65  dle interface re
2b7d0 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62  turns the [datab
2b7e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2b7f0 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69  handle.** to whi
2b800 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ch a [prepared s
2b810 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67  tatement] belong
2b820 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61  s.  ^The [databa
2b830 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
2b840 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2b850 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
2b860 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  is the same [dat
2b870 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b880 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68  ].** that was th
2b890 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2b8a0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
2b8b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2b8c0 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76  ] call (or its v
2b8d0 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77 61  ariants) that wa
2b8e0 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65  s used to.** cre
2b8f0 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
2b900 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 70  t in the first p
2b910 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  lace..*/.sqlite3
2b920 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e   *sqlite3_db_han
2b930 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dle(sqlite3_stmt
2b940 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2b950 52 45 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65  REF: Find the ne
2b960 78 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  xt prepared stat
2b970 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ement.**.** ^Thi
2b980 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
2b990 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2b9a0 20 74 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61   the next [prepa
2b9b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2b9c0 66 74 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73  fter.** pStmt as
2b9d0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
2b9e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2b9f0 65 63 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49  ection] pDb.  ^I
2ba00 66 20 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a  f pStmt is NULL.
2ba10 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74  ** then this int
2ba20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2ba30 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2ba40 66 69 72 73 74 20 70 72 65 70 61 72 65 64 20 73  first prepared s
2ba50 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f  tatement.** asso
2ba60 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
2ba70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2ba80 69 6f 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f  ion pDb.  ^If no
2ba90 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2baa0 65 6e 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73  ent.** satisfies
2bab0 20 74 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20   the conditions 
2bac0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
2bad0 20 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c   it returns NULL
2bae0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74  ..**.** The [dat
2baf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bb00 5d 20 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61  ] pointer D in a
2bb10 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2bb20 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44  ite3_next_stmt(D
2bb30 2c 53 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20  ,S)] must refer 
2bb40 74 6f 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  to an open datab
2bb50 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2bb60 6e 20 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75  n and in particu
2bb70 6c 61 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  lar must not be 
2bb80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2bb90 2a 2f 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  */.sqlite3_stmt 
2bba0 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  *sqlite3_next_st
2bbb0 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c  mt(sqlite3 *pDb,
2bbc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70   sqlite3_stmt *p
2bbd0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2bbe0 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
2bbf0 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
2bc00 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
2bc10 6b 73 20 7b 48 31 32 39 35 30 7d 20 3c 53 36 30  ks {H12950} <S60
2bc20 34 30 30 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  400>.**.** ^The 
2bc30 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
2bc40 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2bc50 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2bc60 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
2bc70 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2bc80 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
2bc90 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54  ction is [COMMIT
2bca0 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a   | committed]..*
2bcb0 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
2bcc0 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
2bcd0 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
2bce0 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
2bcf0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2bd00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2bd10 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
2bd20 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  n..** ^The sqlit
2bd30 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2bd40 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
2bd50 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
2bd60 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
2bd70 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
2bd80 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
2bd90 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20  on is [ROLLBACK 
2bda0 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a  | rolled back]..
2bdb0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
2bdc0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
2bdd0 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
2bde0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
2bdf0 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
2be00 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2be10 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
2be20 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41  dden..** ^The pA
2be30 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70  rg argument is p
2be40 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f  assed through to
2be50 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
2be60 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
2be70 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
2be80 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ook function ret
2be90 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a  urns non-zero,.*
2bea0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  * then the commi
2beb0 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  t is converted i
2bec0 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
2bed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bee0 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
2bef0 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65  ,C,P) and sqlite
2bf00 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2bf10 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73  D,C,P) functions
2bf20 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50  .** return the P
2bf30 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
2bf40 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2bf50 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
2bf60 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20  ction.** on the 
2bf70 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
2bf80 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
2bf90 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65   NULL for.** the
2bfa0 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20   first call for 
2bfb0 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e  each function on
2bfc0 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61   D..**.** The ca
2bfd0 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74  llback implement
2bfe0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
2bff0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
2c000 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
2c010 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c020 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
2c030 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ked the callback
2c040 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
2c050 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
2c060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c070 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
2c080 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
2c090 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
2c0a0 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
2c0b0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
2c0c0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
2c0d0 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20  he commit.** or 
2c0e0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e  rollback hook in
2c0f0 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
2c100 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
2c110 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2c120 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2c130 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
2c140 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
2c150 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c160 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
2c170 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
2c180 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
2c190 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73  ph..**.** ^Regis
2c1a0 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75  tering a NULL fu
2c1b0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
2c1c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  the callback..**
2c1d0 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f  .** ^When the co
2c1e0 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  mmit hook callba
2c1f0 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ck routine retur
2c200 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f  ns zero, the [CO
2c210 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69  MMIT].** operati
2c220 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f  on is allowed to
2c230 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c   continue normal
2c240 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d  ly.  ^If the com
2c250 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75  mit hook.** retu
2c260 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
2c270 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20  en the [COMMIT] 
2c280 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
2c290 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a  o a [ROLLBACK]..
2c2a0 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b  ** ^The rollback
2c2b0 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64   hook is invoked
2c2c0 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74   on a rollback t
2c2d0 68 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  hat results from
2c2e0 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f   a commit.** hoo
2c2f0 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d  k returning non-
2c300 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74  zero, just as it
2c310 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61   would be with a
2c320 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63  ny other rollbac
2c330 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68  k..**.** ^For th
2c340 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68  e purposes of th
2c350 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61  is API, a transa
2c360 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f  ction is said to
2c370 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f   have been.** ro
2c380 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20  lled back if an 
2c390 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41  explicit "ROLLBA
2c3a0 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73  CK" statement is
2c3b0 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a   executed, or.**
2c3c0 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e   an error or con
2c3d0 73 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61  straint causes a
2c3e0 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62  n implicit rollb
2c3f0 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a  ack to occur..**
2c400 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63   ^The rollback c
2c410 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69  allback is not i
2c420 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e  nvoked if a tran
2c430 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75  saction is.** au
2c440 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
2c450 65 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20  ed back because 
2c460 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2c470 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
2c480 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62  d..** ^The rollb
2c490 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ack callback is 
2c4a0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20 61  not invoked if a
2c4b0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a   transaction is.
2c4c0 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ** rolled back b
2c4d0 65 63 61 75 73 65 20 61 20 63 6f 6d 6d 69 74 20  ecause a commit 
2c4e0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 65  callback returne
2c4f0 64 20 6e 6f 6e 2d 7a 65 72 6f 2e 0a 2a 2a 0a 2a  d non-zero..**.*
2c500 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
2c510 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2c520 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ook()] interface
2c530 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2c540 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
2c550 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
2c560 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
2c570 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f  void *sqlite3_ro
2c580 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69  llback_hook(sqli
2c590 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f  te3*, void(*)(vo
2c5a0 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  id *), void*);..
2c5b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c5c0 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69  Data Change Noti
2c5d0 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
2c5e0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
2c5f0 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
2c600 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
2c610 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
2c620 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  ck function.** w
2c630 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
2c640 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64  e connection] id
2c650 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
2c660 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
2c670 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  * to be invoked 
2c680 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69  whenever a row i
2c690 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
2c6a0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
2c6b0 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
2c6c0 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
2c6d0 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
2c6e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20  function.** for 
2c6f0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2c700 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2c710 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a  overridden..**.*
2c720 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
2c730 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
2c740 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74  ter to the funct
2c750 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68  ion to invoke wh
2c760 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75  en a.** row is u
2c770 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
2c780 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
2c790 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2c7a0 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ent to the callb
2c7b0 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ack is a copy of
2c7c0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
2c7d0 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ent.** to sqlite
2c7e0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e  3_update_hook().
2c7f0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2c800 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  callback argumen
2c810 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
2c820 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51  ITE_INSERT], [SQ
2c830 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a  LITE_DELETE],.**
2c840 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41   or [SQLITE_UPDA
2c850 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  TE], depending o
2c860 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  n the operation 
2c870 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20  that caused the 
2c880 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62  callback.** to b
2c890 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54  e invoked..** ^T
2c8a0 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  he third and fou
2c8b0 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  rth arguments to
2c8c0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f   the callback co
2c8d0 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74  ntain pointers t
2c8e0 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  o the.** databas
2c8f0 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65  e and table name
2c900 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
2c910 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a  affected row..**
2c920 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c   ^The final call
2c930 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  back parameter i
2c940 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
2c950 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e   the row..** ^In
2c960 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20   the case of an 
2c970 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73 20  update, this is 
2c980 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65  the [rowid] afte
2c990 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61 6b  r the update tak
2c9a0 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  es place..**.** 
2c9b0 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f  ^(The update hoo
2c9c0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
2c9d0 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73   when internal s
2c9e0 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65  ystem tables are
2c9f0 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e  .** modified (i.
2ca00 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72  e. sqlite_master
2ca10 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75   and sqlite_sequ
2ca20 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ence).)^.**.** ^
2ca30 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 69  In the current i
2ca40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74  mplementation, t
2ca50 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a  he update hook.*
2ca60 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  * is not invoked
2ca70 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f   when duplicatio
2ca80 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  n rows are delet
2ca90 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e  ed because of an
2caa0 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54  .** [ON CONFLICT
2cab0 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52   | ON CONFLICT R
2cac0 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20  EPLACE] clause. 
2cad0 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64   ^Nor is the upd
2cae0 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f  ate hook.** invo
2caf0 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72  ked when rows ar
2cb00 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20  e deleted using 
2cb10 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  the [truncate op
2cb20 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  timization]..** 
2cb30 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64  The exceptions d
2cb40 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70  efined in this p
2cb50 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20 63  aragraph might c
2cb60 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
2cb70 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
2cb80 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
2cb90 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d  e update hook im
2cba0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
2cbb0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
2cbc0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
2cbd0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
2cbe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
2cbf0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75  at invoked the u
2cc00 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79  pdate hook.  Any
2cc10 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
2cc20 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2cc30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
2cc40 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
2cc50 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
2cc60 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
2cc70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2cc80 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
2cc90 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70 64  riggered the upd
2cca0 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74  ate hook..** Not
2ccb0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
2ccc0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2ccd0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
2cce0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
2ccf0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
2cd00 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
2cd10 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
2cd20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
2cd30 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
2cd40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
2cd50 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50  pdate_hook(D,C,P
2cd60 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65  ) function.** re
2cd70 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67 75  turns the P argu
2cd80 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
2cd90 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f  evious call.** o
2cda0 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
2cdb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2cdc0 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
2cdd0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
2cde0 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65  l on D..**.** Se
2cdf0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
2ce00 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2ce10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2ce20 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d  rollback_hook()]
2ce30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  .** interfaces..
2ce40 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
2ce50 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
2ce60 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
2ce70 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
2ce80 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
2ce90 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
2cea0 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
2ceb0 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
2cec0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
2ced0 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
2cee0 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b  Pager Cache.** K
2cef0 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64  EYWORDS: {shared
2cf00 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28   cache}.**.** ^(
2cf10 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  This routine ena
2cf20 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
2cf30 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20   the sharing of 
2cf40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63  the database cac
2cf50 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61  he.** and schema
2cf60 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
2cf70 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61   between [databa
2cf80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20  se connection | 
2cf90 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20  connections].** 
2cfa0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
2cfb0 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73  base. Sharing is
2cfc0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
2cfd0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
2cfe0 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64  .** and disabled
2cff0 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
2d000 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a   is false.)^.**.
2d010 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e  ** ^Cache sharin
2d020 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
2d030 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e   disabled for an
2d040 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
2d050 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68  .** This is a ch
2d060 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
2d070 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
2d080 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
2d090 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a  ns of SQLite,.**
2d0a0 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61   sharing was ena
2d0b0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
2d0c0 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
2d0d0 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
2d0e0 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73  ** ^(The cache s
2d0f0 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
2d100 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
2d110 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
2d120 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
2d130 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
2d140 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
2d150 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
2d160 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2d170 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
2d180 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d190 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
2d1a0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
2d1b0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
2d1c0 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
2d1d0 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
2d1e0 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  pened.)^.**.** ^
2d1f0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  (This routine re
2d200 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
2d210 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
2d220 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
2d230 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63   disabled.** suc
2d240 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
2d250 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2d260 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
2d270 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72  e.)^.**.** ^Shar
2d280 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
2d290 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
2d2a0 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20   But this might 
2d2b0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74  change in.** fut
2d2c0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
2d2d0 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61  SQLite.  Applica
2d2e0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20  tions that care 
2d2f0 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20  about shared.** 
2d300 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68  cache setting sh
2d310 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c  ould set it expl
2d320 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  icitly..**.** Se
2d330 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65  e Also:  [SQLite
2d340 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f   Shared-Cache Mo
2d350 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  de].*/.int sqlit
2d360 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
2d370 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
2d380 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74  .** CAPI3REF: At
2d390 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
2d3a0 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20  ap Memory.**.** 
2d3b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
2d3c0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e  ease_memory() in
2d3d0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2d3e0 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73   to free N bytes
2d3f0 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  .** of heap memo
2d400 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
2d410 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
2d420 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2d430 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74  ons.** held by t
2d440 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72  he database libr
2d450 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73  ary.   Memory us
2d460 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
2d470 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f  base.** pages to
2d480 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
2d490 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70  ance is an examp
2d4a0 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74  le of non-essent
2d4b0 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ial memory..** ^
2d4c0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2d4d0 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
2d4e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d4f0 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
2d500 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69  eed,.** which mi
2d510 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
2d520 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  ess than the amo
2d530 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
2d540 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
2d550 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e 74  lease_memory(int
2d560 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d570 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d  EF: Impose A Lim
2d580 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a  it On Heap Size.
2d590 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2d5a0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
2d5b0 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 70  it() interface p
2d5c0 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20 6c  laces a "soft" l
2d5d0 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 61  imit.** on the a
2d5e0 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65  mount of heap me
2d5f0 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62 65  mory that may be
2d600 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
2d610 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20  Lite..** ^If an 
2d620 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61 74  internal allocat
2d630 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2d640 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63 65   that would exce
2d650 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 68  ed the.** soft h
2d660 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c 69  eap limit, [sqli
2d670 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
2d680 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65 64  ry()] is invoked
2d690 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   one or.** more 
2d6a0 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75 70  times to free up
2d6b0 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66 6f   some space befo
2d6c0 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  re the allocatio
2d6d0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 0a  n is performed..
2d6e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69 74  **.** ^The limit
2d6f0 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66 74   is called "soft
2d700 22 2c 20 62 65 63 61 75 73 65 20 69 66 20 5b 73  ", because if [s
2d710 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2d720 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e  emory()].** cann
2d730 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65  ot free sufficie
2d740 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65  nt memory to pre
2d750 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66  vent the limit f
2d760 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64  rom being exceed
2d770 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  ed,.** the memor
2d780 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61  y is allocated a
2d790 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75  nyway and the cu
2d7a0 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrent operation 
2d7b0 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  proceeds..**.** 
2d7c0 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a  ^A negative or z
2d7d0 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20  ero value for N 
2d7e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
2d7f0 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70   is no soft heap
2d800 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73   limit and.** [s
2d810 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2d820 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
2d830 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2d840 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61  n memory is exha
2d850 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  usted..** ^The d
2d860 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
2d870 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2d880 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
2d890 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b  .** ^(SQLite mak
2d8a0 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
2d8b0 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
2d8c0 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a  ft heap limit..*
2d8d0 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66  * But if the sof
2d8e0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
2d8f0 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20  not be honored, 
2d900 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
2d910 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
2d920 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
2d930 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69  fication.)^  Thi
2d940 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
2d950 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20  it is.** called 
2d960 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
2d970 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
2d980 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
2d990 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
2d9a0 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
2d9b0 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
2d9c0 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
2d9d0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
2d9e0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
2d9f0 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
2da00 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
2da10 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
2da20 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
2da30 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
2da40 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
2da50 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
2da60 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
2da70 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
2da80 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2da90 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2daa0 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
2dab0 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
2dac0 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
2dad0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
2dae0 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e   all threads. In
2daf0 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
2db00 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
2db10 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
2db20 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
2db30 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
2db40 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
2db50 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
2db60 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
2db70 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2db80 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65  3REF: Extract Me
2db90 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
2dba0 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
2dbb0 20 7b 48 31 32 38 35 30 7d 20 3c 53 36 30 33 30   {H12850} <S6030
2dbc0 30 3e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  0>.**.** ^This r
2dbd0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d  outine returns m
2dbe0 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20  etadata about a 
2dbf0 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20  specific column 
2dc00 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a  of a specific.**
2dc10 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
2dc20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67  accessible using
2dc30 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2dc40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
2dc50 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  e.** passed as t
2dc60 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f  he first functio
2dc70 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  n argument..**.*
2dc80 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73  * ^The column is
2dc90 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
2dca0 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64  he second, third
2dcb0 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61   and fourth para
2dcc0 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69  meters to.** thi
2dcd0 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 28 54 68  s function. ^(Th
2dce0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2dcf0 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
2dd00 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2dd10 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
2dd20 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 20 6f 72  main", "temp" or
2dd30 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74   an attached dat
2dd40 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e  abase) containin
2dd50 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a  g the specified.
2dd60 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c  ** table or NULL
2dd70 2e 20 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c  . If it is NULL,
2dd80 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
2dd90 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
2dda0 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
2ddb0 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
2ddc0 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
2ddd0 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20  thm used by the 
2dde0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
2ddf0 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  to.** resolve un
2de00 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
2de10 72 65 66 65 72 65 6e 63 65 73 2e 29 5e 0a 2a 2a  references.)^.**
2de20 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2de30 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
2de40 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
2de50 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
2de60 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a  ble and column.*
2de70 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65  * name of the de
2de80 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65  sired column, re
2de90 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74  spectively. Neit
2dea0 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72  her of these par
2deb0 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62  ameters.** may b
2dec0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d  e NULL..**.** ^M
2ded0 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72  etadata is retur
2dee0 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74  ned by writing t
2def0 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63  o the memory loc
2df00 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73  ations passed as
2df10 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20   the 5th.** and 
2df20 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
2df30 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
2df40 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20  nction. ^Any of 
2df50 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20  these arguments 
2df60 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20  may be.** NULL, 
2df70 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
2df80 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2df90 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64  element of metad
2dfa0 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ata is omitted..
2dfb0 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75  **.** ^(<blockqu
2dfc0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2dfd0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2dfe0 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72  r><th> Parameter
2dff0 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e   <th> Output<br>
2e000 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72  Type <th>  Descr
2e010 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  iption.**.** <tr
2e020 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63  ><td> 5th <td> c
2e030 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2e040 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72  Data type.** <tr
2e050 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63  ><td> 6th <td> c
2e060 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
2e070 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20  Name of default 
2e080 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2e090 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37  ce.** <tr><td> 7
2e0a0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
2e0b0 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
2e0c0 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f   column has a NO
2e0d0 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
2e0e0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74  t.** <tr><td> 8t
2e0f0 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2e100 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2e110 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f  column is part o
2e120 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45  f the PRIMARY KE
2e130 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74  Y.** <tr><td> 9t
2e140 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
2e150 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
2e160 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49  column is [AUTOI
2e170 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74  NCREMENT].** </t
2e180 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2e190 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
2e1a0 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  The memory point
2e1b0 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61  ed to by the cha
2e1c0 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20  racter pointers 
2e1d0 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65  returned for the
2e1e0 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20  .** declaration 
2e1f0 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69  type and collati
2e200 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76  on sequence is v
2e210 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20  alid only until 
2e220 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c  the next.** call
2e230 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41   to any SQLite A
2e240 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
2e250 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
2e260 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63  fied table is ac
2e270 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61  tually a view, a
2e280 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
2e290 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
2e2a0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
2e2b0 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72  ied column is "r
2e2c0 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20  owid", "oid" or 
2e2d0 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e  "_rowid_" and an
2e2e0 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49  .** [INTEGER PRI
2e2f0 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
2e300 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
2e310 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
2e320 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
2e330 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
2e340 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70   set for the exp
2e350 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2e360 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68   column. ^(If th
2e370 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
2e380 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
2e390 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2e3a0 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74  Y KEY] column, t
2e3b0 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
2e3c0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
2e3d0 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   set as follows:
2e3e0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
2e3f0 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
2e400 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
2e410 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2e420 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
2e430 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
2e440 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
2e450 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
2e460 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
2e470 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
2e480 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
2e490 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72   may load one or
2e4a0 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72   more schemas fr
2e4b0 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  om database file
2e4c0 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f  s. If an.** erro
2e4d0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
2e4e0 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72  this process, or
2e4f0 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65   if the requeste
2e500 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  d table or colum
2e510 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66  n.** cannot be f
2e520 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20  ound, an [error 
2e530 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2e540 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
2e550 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69  essage left.** i
2e560 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
2e570 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20  connection] (to 
2e580 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69  be retrieved usi
2e590 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  ng sqlite3_errms
2e5a0 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  g()).)^.**.** ^T
2e5b0 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20  his API is only 
2e5c0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2e5d0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2e5e0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2e5f0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2e600 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2e610 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2e620 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
2e630 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e640 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74  table_column_met
2e650 61 64 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33  adata(.  sqlite3
2e660 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2e670 20 20 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69       /* Connecti
2e680 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  on handle */.  c
2e690 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61  onst char *zDbNa
2e6a0 6d 65 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61  me,        /* Da
2e6b0 74 61 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e  tabase name or N
2e6c0 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ULL */.  const c
2e6d0 68 61 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c  har *zTableName,
2e6e0 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61       /* Table na
2e6f0 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  me */.  const ch
2e700 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c  ar *zColumnName,
2e710 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61      /* Column na
2e720 6d 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e  me */.  char con
2e730 73 74 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c  st **pzDataType,
2e740 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44      /* OUTPUT: D
2e750 65 63 6c 61 72 65 64 20 64 61 74 61 20 74 79 70  eclared data typ
2e760 65 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73  e */.  char cons
2e770 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20  t **pzCollSeq,  
2e780 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f     /* OUTPUT: Co
2e790 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2e7a0 20 6e 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   name */.  int *
2e7b0 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20  pNotNull,       
2e7c0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
2e7d0 3a 20 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55  : True if NOT NU
2e7e0 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78  LL constraint ex
2e7f0 69 73 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  ists */.  int *p
2e800 50 72 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20  PrimaryKey,     
2e810 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a        /* OUTPUT:
2e820 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
2e830 70 61 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20  part of PK */.  
2e840 69 6e 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20  int *pAutoinc   
2e850 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
2e860 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
2e870 6f 6c 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e  olumn is auto-in
2e880 63 72 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f  crement */.);../
2e890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
2e8a0 6f 61 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e  oad An Extension
2e8b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
2e8c0 65 72 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20  erface loads an 
2e8d0 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
2e8e0 20 6c 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68   library from th
2e8f0 65 20 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a  e named file..**
2e900 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e910 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2e920 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2e930 6d 70 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a  mpts to load an.
2e940 2a 2a 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73  ** SQLite extens
2e950 69 6f 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  ion library cont
2e960 61 69 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c  ained in the fil
2e970 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  e zFile..**.** ^
2e980 54 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  The entry point 
2e990 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50  is zProc..** ^zP
2e9a0 72 6f 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e  roc may be 0, in
2e9b0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
2e9c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72  name of the entr
2e9d0 79 20 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75  y point.** defau
2e9e0 6c 74 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f  lts to "sqlite3_
2e9f0 65 78 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e  extension_init".
2ea00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ea10 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2ea20 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2ea30 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  rns.** [SQLITE_O
2ea40 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e  K] on success an
2ea50 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2ea60 20 69 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f   if something go
2ea70 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66  es wrong..** ^If
2ea80 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
2ea90 20 61 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73   and pzErrMsg is
2eaa0 20 6e 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65   not 0, then the
2eab0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  .** [sqlite3_loa
2eac0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69  d_extension()] i
2ead0 6e 74 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61  nterface shall a
2eae0 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c  ttempt to.** fil
2eaf0 6c 20 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68  l *pzErrMsg with
2eb00 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
2eb10 65 78 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65  ext stored in me
2eb20 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64  mory.** obtained
2eb30 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2eb40 61 6c 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61  alloc()]. The ca
2eb50 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a  lling function.*
2eb60 2a 20 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68  * should free th
2eb70 69 73 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c  is memory by cal
2eb80 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  ling [sqlite3_fr
2eb90 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78  ee()]..**.** ^Ex
2eba0 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20  tension loading 
2ebb0 6d 75 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20  must be enabled 
2ebc0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2ebd0 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
2ebe0 74 65 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72  tension()] prior
2ebf0 20 74 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73   to calling this
2ec00 20 41 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69   API,.** otherwi
2ec10 73 65 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c  se an error will
2ec20 20 62 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   be returned..**
2ec30 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
2ec40 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
2ec50 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
2ec60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ec70 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
2ec80 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2ec90 20 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64           /* Load
2eca0 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69   the extension i
2ecb0 6e 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73  nto this databas
2ecc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a  e connection */.
2ecd0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
2ece0 69 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ile,    /* Name 
2ecf0 6f 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69  of the shared li
2ed00 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  brary containing
2ed10 20 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20   extension */.  
2ed20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f  const char *zPro
2ed30 63 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70  c,    /* Entry p
2ed40 6f 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66  oint.  Derived f
2ed50 72 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a  rom zFile if 0 *
2ed60 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
2ed70 4d 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74  Msg       /* Put
2ed80 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68   error message h
2ed90 65 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a  ere if not 0 */.
2eda0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2edb0 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
2edc0 73 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20  sable Extension 
2edd0 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53  Loading.**.** ^S
2ede0 6f 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e  o as not to open
2edf0 20 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20   security holes 
2ee00 69 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61  in older applica
2ee10 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a  tions that are.*
2ee20 2a 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20  * unprepared to 
2ee30 64 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73  deal with extens
2ee40 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64  ion loading, and
2ee50 20 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64   as a means of d
2ee60 69 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65  isabling.** exte
2ee70 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68  nsion loading wh
2ee80 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75  ile evaluating u
2ee90 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c  ser-entered SQL,
2eea0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41   the following A
2eeb0 50 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65  PI.** is provide
2eec0 64 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73  d to turn the [s
2eed0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
2eee0 6e 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69  nsion()] mechani
2eef0 73 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a  sm on and off..*
2ef00 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20  *.** ^Extension 
2ef10 6c 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62  loading is off b
2ef20 79 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74  y default. See t
2ef30 69 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20  icket #1863..** 
2ef40 5e 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65  ^Call the sqlite
2ef50 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
2ef60 74 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e  tension() routin
2ef70 65 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a  e with onoff==1.
2ef80 2a 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e  ** to turn exten
2ef90 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20  sion loading on 
2efa0 61 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68  and call it with
2efb0 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72   onoff==0 to tur
2efc0 6e 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66  n.** it back off
2efd0 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73   again..*/.int s
2efe0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
2eff0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c  ad_extension(sql
2f000 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e  ite3 *db, int on
2f010 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
2f020 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63  I3REF: Automatic
2f030 61 6c 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74  ally Load An Ext
2f040 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  ensions.**.** ^T
2f050 68 69 73 20 41 50 49 20 63 61 6e 20 62 65 20 69  his API can be i
2f060 6e 76 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61  nvoked at progra
2f070 6d 20 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64  m startup in ord
2f080 65 72 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a  er to register.*
2f090 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74  * one or more st
2f0a0 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20  atically linked 
2f0b0 65 78 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20  extensions that 
2f0c0 77 69 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c  will be availabl
2f0d0 65 0a 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20  e.** to all new 
2f0e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2f0f0 74 69 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tions]..**.** ^(
2f100 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  This routine sto
2f110 72 65 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  res a pointer to
2f120 20 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65   the extension e
2f130 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e  ntry point.** in
2f140 20 61 6e 20 61 72 72 61 79 20 74 68 61 74 20 69   an array that i
2f150 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
2f160 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
2f170 29 5d 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79  )].  That memory
2f180 0a 2a 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74  .** is deallocat
2f190 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72  ed by [sqlite3_r
2f1a0 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
2f1b0 69 6f 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ion()].)^.**.** 
2f1c0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
2f1d0 65 67 69 73 74 65 72 73 20 61 6e 20 65 78 74 65  egisters an exte
2f1e0 6e 73 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e  nsion entry poin
2f1f0 74 20 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74  t that is.** aut
2f200 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b  omatically invok
2f210 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65  ed whenever a ne
2f220 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
2f230 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70  ection].** is op
2f240 65 6e 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ened using [sqli
2f250 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
2f260 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
2f270 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
2f280 6f 70 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e  open_v2()]..** ^
2f290 44 75 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73  Duplicate extens
2f2a0 69 6f 6e 73 20 61 72 65 20 64 65 74 65 63 74 65  ions are detecte
2f2b0 64 20 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69  d so calling thi
2f2c0 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c  s routine.** mul
2f2d0 74 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68  tiple times with
2f2e0 20 74 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73   the same extens
2f2f0 69 6f 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e  ion is harmless.
2f300 0a 2a 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65  .** ^Automatic e
2f310 78 74 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20  xtensions apply 
2f320 61 63 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61  across all threa
2f330 64 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ds..*/.int sqlit
2f340 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
2f350 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50  n(void (*xEntryP
2f360 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f  oint)(void));../
2f370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2f380 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
2f390 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
2f3a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75  .**.** ^(This fu
2f3b0 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20  nction disables 
2f3c0 61 6c 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72  all previously r
2f3d0 65 67 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61  egistered automa
2f3e0 74 69 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e  tic.** extension
2f3f0 73 2e 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65  s. It undoes the
2f400 20 65 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70   effect of all p
2f410 72 69 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rior.** [sqlite3
2f420 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
2f430 29 5d 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a  )] calls.)^.**.*
2f440 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
2f450 20 64 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61   disables automa
2f460 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69  tic extensions i
2f470 6e 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a  n all threads..*
2f480 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
2f490 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
2f4a0 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ion(void);../*.*
2f4b0 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54  ***** EXPERIMENT
2f4c0 41 4c 20 2d 20 73 75 62 6a 65 63 74 20 74 6f 20  AL - subject to 
2f4d0 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 20 6e  change without n
2f4e0 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  otice **********
2f4f0 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ****.**.** The i
2f500 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
2f510 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
2f520 63 68 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65  chanism is curre
2f530 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
2f540 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
2f550 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
2f560 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
2f570 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
2f580 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
2f590 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
2f5a0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
2f5b0 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
2f5c0 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
2f5d0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
2f5e0 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
2f5f0 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
2f600 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
2f610 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
2f620 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
2f630 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
2f640 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
2f650 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
2f660 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72  ../*.** Structur
2f670 65 73 20 75 73 65 64 20 62 79 20 74 68 65 20 76  es used by the v
2f680 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74  irtual table int
2f690 65 72 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65  erface.*/.typede
2f6a0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2f6b0 5f 76 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74  _vtab sqlite3_vt
2f6c0 61 62 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75  ab;.typedef stru
2f6d0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
2f6e0 5f 69 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e  _info sqlite3_in
2f6f0 64 65 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65  dex_info;.typede
2f700 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2f710 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c  _vtab_cursor sql
2f720 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2f730 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
2f740 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
2f750 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a  sqlite3_module;.
2f760 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f770 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f   Virtual Table O
2f780 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2f790 53 3a 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c  S: sqlite3_modul
2f7a0 65 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e {virtual table
2f7b0 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 20 45 58 50 45   module}.** EXPE
2f7c0 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 54  RIMENTAL.**.** T
2f7d0 68 69 73 20 73 74 72 75 63 74 75 72 65 2c 20 73  his structure, s
2f7e0 6f 6d 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20  ometimes called 
2f7f0 61 20 61 20 22 76 69 72 74 75 61 6c 20 74 61 62  a a "virtual tab
2f800 6c 65 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20  le module", .** 
2f810 64 65 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c  defines the impl
2f820 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20  ementation of a 
2f830 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
2f840 2e 20 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75  .  .** This stru
2f850 63 74 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d  cture consists m
2f860 6f 73 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73  ostly of methods
2f870 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
2f880 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61  .**.** ^A virtua
2f890 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69  l table module i
2f8a0 73 20 63 72 65 61 74 65 64 20 62 79 20 66 69 6c  s created by fil
2f8b0 6c 69 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73  ling in a persis
2f8c0 74 65 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  tent.** instance
2f8d0 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
2f8e0 72 65 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61  re and passing a
2f8f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74   pointer to that
2f900 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20   instance.** to 
2f910 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2f920 6d 6f 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71  module()] or [sq
2f930 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
2f940 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54  ule_v2()]..** ^T
2f950 68 65 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20  he registration 
2f960 72 65 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e  remains valid un
2f970 74 69 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63  til it is replac
2f980 65 64 20 62 79 20 61 20 64 69 66 66 65 72 65 6e  ed by a differen
2f990 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75  t.** module or u
2f9a0 6e 74 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61  ntil the [databa
2f9b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63  se connection] c
2f9c0 6c 6f 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74  loses.  The cont
2f9d0 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73  ent.** of this s
2f9e0 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f  tructure must no
2f9f0 74 20 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69  t change while i
2fa00 74 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20  t is registered 
2fa10 77 69 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61  with.** any data
2fa20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
2fa30 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
2fa40 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e  e3_module {.  in
2fa50 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
2fa60 74 20 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c  t (*xCreate)(sql
2fa70 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75  ite3*, void *pAu
2fa80 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  x,.             
2fa90 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73    int argc, cons
2faa0 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72  t char *const*ar
2fab0 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  gv,.            
2fac0 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20     sqlite3_vtab 
2fad0 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a  **ppVTab, char**
2fae0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e  );.  int (*xConn
2faf0 65 63 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76  ect)(sqlite3*, v
2fb00 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20  oid *pAux,.     
2fb10 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
2fb20 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  gc, const char *
2fb30 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20  const*argv,.    
2fb40 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74             sqlit
2fb50 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62  e3_vtab **ppVTab
2fb60 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74  , char**);.  int
2fb70 20 28 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73   (*xBestIndex)(s
2fb80 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2fb90 61 62 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  ab, sqlite3_inde
2fba0 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20  x_info*);.  int 
2fbb0 28 2a 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73  (*xDisconnect)(s
2fbc0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2fbd0 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  ab);.  int (*xDe
2fbe0 73 74 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76  stroy)(sqlite3_v
2fbf0 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
2fc00 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69  nt (*xOpen)(sqli
2fc10 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
2fc20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
2fc30 72 73 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29  rsor **ppCursor)
2fc40 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
2fc50 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
2fc60 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
2fc70 2a 78 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65  *xFilter)(sqlite
2fc80 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
2fc90 69 6e 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73  int idxNum, cons
2fca0 74 20 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a  t char *idxStr,.
2fcb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2fcc0 69 6e 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65  int argc, sqlite
2fcd0 33 5f 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b  3_value **argv);
2fce0 0a 20 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28  .  int (*xNext)(
2fcf0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
2fd00 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
2fd10 45 6f 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61  Eof)(sqlite3_vta
2fd20 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
2fd30 74 20 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c  t (*xColumn)(sql
2fd40 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
2fd50 2a 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  *, sqlite3_conte
2fd60 78 74 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  xt*, int);.  int
2fd70 20 28 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74   (*xRowid)(sqlit
2fd80 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
2fd90 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
2fda0 70 52 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28  pRowid);.  int (
2fdb0 2a 78 55 70 64 61 74 65 29 28 73 71 6c 69 74 65  *xUpdate)(sqlite
2fdc0 33 5f 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73  3_vtab *, int, s
2fdd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c  qlite3_value **,
2fde0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
2fdf0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69  );.  int (*xBegi
2fe00 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
2fe10 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
2fe20 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
2fe30 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
2fe40 69 6e 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73  int (*xCommit)(s
2fe50 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54  qlite3_vtab *pVT
2fe60 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  ab);.  int (*xRo
2fe70 6c 6c 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f  llback)(sqlite3_
2fe80 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
2fe90 69 6e 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74  int (*xFindFunct
2fea0 69 6f 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ion)(sqlite3_vta
2feb0 62 20 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41  b *pVtab, int nA
2fec0 72 67 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  rg, const char *
2fed0 7a 4e 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20  zName,.         
2fee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2fef0 69 64 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71  id (**pxFunc)(sq
2ff00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2ff10 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2ff20 2a 2a 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20  **),.           
2ff30 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2ff40 20 2a 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74   **ppArg);.  int
2ff50 20 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69   (*xRename)(sqli
2ff60 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c  te3_vtab *pVtab,
2ff70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65   const char *zNe
2ff80 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  w);.};../*.** CA
2ff90 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
2ffa0 54 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49  Table Indexing I
2ffb0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45  nformation.** KE
2ffc0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
2ffd0 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 20 45 58  index_info.** EX
2ffe0 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a  PERIMENTAL.**.**
2fff0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64   The sqlite3_ind
30000 65 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72  ex_info structur
30010 65 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72  e and its substr
30020 75 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20  uctures is used 
30030 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72  to.** pass infor
30040 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20  mation into and 
30050 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c  receive the repl
30060 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73  y from the [xBes
30070 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f  tIndex].** metho
30080 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  d of a [virtual 
30090 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
300a0 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72  The fields under
300b0 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20   **Inputs** are 
300c0 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f  the.** inputs to
300d0 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20   xBestIndex and 
300e0 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20  are read-only.  
300f0 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72  xBestIndex inser
30100 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74  ts its.** result
30110 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74  s into the **Out
30120 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a  puts** fields..*
30130 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73  *.** ^(The aCons
30140 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72  traint[] array r
30150 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61  ecords WHERE cla
30160 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
30170 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a  of the form:.**.
30180 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75 6d 6e 20 4f  ** <pre>column O
30190 50 20 65 78 70 72 3c 2f 70 72 65 3e 0a 2a 2a 0a  P expr</pre>.**.
301a0 2a 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d  ** where OP is =
301b0 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26  , &lt;, &lt;=, &
301c0 67 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e  gt;, or &gt;=.)^
301d0 20 20 5e 54 68 65 20 70 61 72 74 69 63 75 6c 61    ^The particula
301e0 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a  r operator is.**
301f0 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73   stored in aCons
30200 74 72 61 69 6e 74 5b 5d 2e 6f 70 2e 20 20 5e 54  traint[].op.  ^T
30210 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
30220 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64  column is stored
30230 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69   in.** aConstrai
30240 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 20 20 5e  nt[].iColumn.  ^
30250 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 75  (aConstraint[].u
30260 73 61 62 6c 65 20 69 73 20 54 52 55 45 20 69 66  sable is TRUE if
30270 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f 6e 20   the.** expr on 
30280 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64 20 73  the right-hand s
30290 69 64 65 20 63 61 6e 20 62 65 20 65 76 61 6c 75  ide can be evalu
302a0 61 74 65 64 20 28 61 6e 64 20 74 68 75 73 20 74  ated (and thus t
302b0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a  he constraint.**
302c0 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e 64 20   is usable) and 
302d0 66 61 6c 73 65 20 69 66 20 69 74 20 63 61 6e 6e  false if it cann
302e0 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ot.)^.**.** ^The
302f0 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74 6f 6d   optimizer autom
30300 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72 74 73  atically inverts
30310 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20 66 6f   terms of the fo
30320 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f 6c 75  rm "expr OP colu
30330 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b 65 73  mn".** and makes
30340 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66 69 63   other simplific
30350 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20 57 48  ations to the WH
30360 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20 61 6e  ERE clause in an
30370 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a 20 67   attempt to.** g
30380 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45 52 45  et as many WHERE
30390 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20 69 6e   clause terms in
303a0 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68 6f 77  to the form show
303b0 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73 73 69  n above as possi
303c0 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61 43 6f  ble..** ^The aCo
303d0 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79  nstraint[] array
303e0 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 57 48   only reports WH
303f0 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73  ERE clause terms
30400 20 69 6e 20 74 68 65 20 63 6f 72 72 65 63 74 0a   in the correct.
30410 2a 2a 20 66 6f 72 6d 20 74 68 61 74 20 72 65 66  ** form that ref
30420 65 72 20 74 6f 20 74 68 65 20 70 61 72 74 69 63  er to the partic
30430 75 6c 61 72 20 76 69 72 74 75 61 6c 20 74 61 62  ular virtual tab
30440 6c 65 20 62 65 69 6e 67 20 71 75 65 72 69 65 64  le being queried
30450 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61  ..**.** ^Informa
30460 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f  tion about the O
30470 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 69  RDER BY clause i
30480 73 20 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64  s stored in aOrd
30490 65 72 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68  erBy[]..** ^Each
304a0 20 74 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42   term of aOrderB
304b0 79 20 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75  y records a colu
304c0 6d 6e 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20  mn of the ORDER 
304d0 42 59 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a  BY clause..**.**
304e0 20 54 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78   The [xBestIndex
304f0 5d 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69  ] method must fi
30500 6c 6c 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  ll aConstraintUs
30510 61 67 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72  age[] with infor
30520 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
30530 77 68 61 74 20 70 61 72 61 6d 65 74 65 72 73 20  what parameters 
30540 74 6f 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74  to pass to xFilt
30550 65 72 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64  er.  ^If argvInd
30560 65 78 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ex>0 then.** the
30570 20 72 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65   right-hand side
30580 20 6f 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   of the correspo
30590 6e 64 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e  nding aConstrain
305a0 74 5b 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64  t[] is evaluated
305b0 0a 2a 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20  .** and becomes 
305c0 74 68 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68  the argvIndex-th
305d0 20 65 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20   entry in argv. 
305e0 20 5e 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e   ^(If aConstrain
305f0 74 55 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a  tUsage[].omit.**
30600 20 69 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74   is true, then t
30610 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  he constraint is
30620 20 61 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66   assumed to be f
30630 75 6c 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20  ully handled by 
30640 74 68 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74  the.** virtual t
30650 61 62 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20  able and is not 
30660 63 68 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79  checked again by
30670 20 53 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a   SQLite.)^.**.**
30680 20 5e 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64   ^The idxNum and
30690 20 69 64 78 50 74 72 20 76 61 6c 75 65 73 20 61   idxPtr values a
306a0 72 65 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20  re recorded and 
306b0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a  passed into the.
306c0 2a 2a 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74  ** [xFilter] met
306d0 68 6f 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65  hod..** ^[sqlite
306e0 33 5f 66 72 65 65 28 29 5d 20 69 73 20 75 73 65  3_free()] is use
306f0 64 20 74 6f 20 66 72 65 65 20 69 64 78 50 74 72  d to free idxPtr
30700 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 66   if and only iff
30710 0a 2a 2a 20 6e 65 65 64 54 6f 46 72 65 65 49 64  .** needToFreeId
30720 78 50 74 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a  xPtr is true..**
30730 0a 2a 2a 20 5e 54 68 65 20 6f 72 64 65 72 42 79  .** ^The orderBy
30740 43 6f 6e 73 75 6d 65 64 20 6d 65 61 6e 73 20 74  Consumed means t
30750 68 61 74 20 6f 75 74 70 75 74 20 66 72 6f 6d 20  hat output from 
30760 5b 78 46 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74  [xFilter]/[xNext
30770 5d 20 77 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a  ] will occur in.
30780 2a 2a 20 74 68 65 20 63 6f 72 72 65 63 74 20 6f  ** the correct o
30790 72 64 65 72 20 74 6f 20 73 61 74 69 73 66 79 20  rder to satisfy 
307a0 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
307b0 75 73 65 20 73 6f 20 74 68 61 74 20 6e 6f 20 73  use so that no s
307c0 65 70 61 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69  eparate.** sorti
307d0 6e 67 20 73 74 65 70 20 69 73 20 72 65 71 75 69  ng step is requi
307e0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
307f0 65 73 74 69 6d 61 74 65 64 43 6f 73 74 20 76 61  estimatedCost va
30800 6c 75 65 20 69 73 20 61 6e 20 65 73 74 69 6d 61  lue is an estima
30810 74 65 20 6f 66 20 74 68 65 20 63 6f 73 74 20 6f  te of the cost o
30820 66 20 64 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70  f doing the.** p
30830 61 72 74 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70  articular lookup
30840 2e 20 20 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f  .  A full scan o
30850 66 20 61 20 74 61 62 6c 65 20 77 69 74 68 20 4e  f a table with N
30860 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
30870 68 61 76 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f  have.** a cost o
30880 66 20 4e 2e 20 20 41 20 62 69 6e 61 72 79 20 73  f N.  A binary s
30890 65 61 72 63 68 20 6f 66 20 61 20 74 61 62 6c 65  earch of a table
308a0 20 6f 66 20 4e 20 65 6e 74 72 69 65 73 20 73 68   of N entries sh
308b0 6f 75 6c 64 20 68 61 76 65 20 61 0a 2a 2a 20 63  ould have a.** c
308c0 6f 73 74 20 6f 66 20 61 70 70 72 6f 78 69 6d 61  ost of approxima
308d0 74 65 6c 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a  tely log(N)..*/.
308e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
308f0 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a  ndex_info {.  /*
30900 20 49 6e 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74   Inputs */.  int
30910 20 6e 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20   nConstraint;   
30920 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
30930 72 20 6f 66 20 65 6e 74 72 69 65 73 20 69 6e 20  r of entries in 
30940 61 43 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20  aConstraint */. 
30950 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
30960 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74  index_constraint
30970 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c   {.     int iCol
30980 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  umn;            
30990 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c    /* Column on l
309a0 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
309b0 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20   constraint */. 
309c0 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
309d0 72 20 6f 70 3b 20 20 20 20 20 20 20 20 20 2f 2a  r op;         /*
309e0 20 43 6f 6e 73 74 72 61 69 6e 74 20 6f 70 65 72   Constraint oper
309f0 61 74 6f 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73  ator */.     uns
30a00 69 67 6e 65 64 20 63 68 61 72 20 75 73 61 62 6c  igned char usabl
30a10 65 3b 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69  e;     /* True i
30a20 66 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  f this constrain
30a30 74 20 69 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20  t is usable */. 
30a40 20 20 20 20 69 6e 74 20 69 54 65 72 6d 4f 66 66      int iTermOff
30a50 73 65 74 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  set;          /*
30a60 20 55 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   Used internally
30a70 20 2d 20 78 42 65 73 74 49 6e 64 65 78 20 73 68   - xBestIndex sh
30a80 6f 75 6c 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20  ould ignore */. 
30a90 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b   } *aConstraint;
30aa0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 54              /* T
30ab0 61 62 6c 65 20 6f 66 20 57 48 45 52 45 20 63 6c  able of WHERE cl
30ac0 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
30ad0 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72   */.  int nOrder
30ae0 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  By;             
30af0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 74 65   /* Number of te
30b00 72 6d 73 20 69 6e 20 74 68 65 20 4f 52 44 45 52  rms in the ORDER
30b10 20 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20   BY clause */.  
30b20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
30b30 6e 64 65 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20  ndex_orderby {. 
30b40 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
30b50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
30b60 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a   Column number *
30b70 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64 20  /.     unsigned 
30b80 63 68 61 72 20 64 65 73 63 3b 20 20 20 20 20 20  char desc;      
30b90 20 2f 2a 20 54 72 75 65 20 66 6f 72 20 44 45 53   /* True for DES
30ba0 43 2e 20 20 46 61 6c 73 65 20 66 6f 72 20 41 53  C.  False for AS
30bb0 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65  C. */.  } *aOrde
30bc0 72 42 79 3b 20 20 20 20 20 20 20 20 20 20 20 20  rBy;            
30bd0 20 20 20 2f 2a 20 54 68 65 20 4f 52 44 45 52 20     /* The ORDER 
30be0 42 59 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f  BY clause */.  /
30bf0 2a 20 4f 75 74 70 75 74 73 20 2a 2f 0a 20 20 73  * Outputs */.  s
30c00 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e  truct sqlite3_in
30c10 64 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75  dex_constraint_u
30c20 73 61 67 65 20 7b 0a 20 20 20 20 69 6e 74 20 61  sage {.    int a
30c30 72 67 76 49 6e 64 65 78 3b 20 20 20 20 20 20 20  rgvIndex;       
30c40 20 20 20 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f      /* if >0, co
30c50 6e 73 74 72 61 69 6e 74 20 69 73 20 70 61 72 74  nstraint is part
30c60 20 6f 66 20 61 72 67 76 20 74 6f 20 78 46 69 6c   of argv to xFil
30c70 74 65 72 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67  ter */.    unsig
30c80 6e 65 64 20 63 68 61 72 20 6f 6d 69 74 3b 20 20  ned char omit;  
30c90 20 20 20 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f      /* Do not co
30ca0 64 65 20 61 20 74 65 73 74 20 66 6f 72 20 74 68  de a test for th
30cb0 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f  is constraint */
30cc0 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e  .  } *aConstrain
30cd0 74 55 73 61 67 65 3b 0a 20 20 69 6e 74 20 69 64  tUsage;.  int id
30ce0 78 4e 75 6d 3b 20 20 20 20 20 20 20 20 20 20 20  xNum;           
30cf0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75       /* Number u
30d00 73 65 64 20 74 6f 20 69 64 65 6e 74 69 66 79 20  sed to identify 
30d10 74 68 65 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63  the index */.  c
30d20 68 61 72 20 2a 69 64 78 53 74 72 3b 20 20 20 20  har *idxStr;    
30d30 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
30d40 69 6e 67 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62  ing, possibly ob
30d50 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69  tained from sqli
30d60 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20  te3_malloc */.  
30d70 69 6e 74 20 6e 65 65 64 54 6f 46 72 65 65 49 64  int needToFreeId
30d80 78 53 74 72 3b 20 20 20 20 20 20 2f 2a 20 46 72  xStr;      /* Fr
30d90 65 65 20 69 64 78 53 74 72 20 75 73 69 6e 67 20  ee idxStr using 
30da0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
30db0 66 20 74 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20  f true */.  int 
30dc0 6f 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b  orderByConsumed;
30dd0 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 69         /* True i
30de0 66 20 6f 75 74 70 75 74 20 69 73 20 61 6c 72 65  f output is alre
30df0 61 64 79 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20  ady ordered */. 
30e00 20 64 6f 75 62 6c 65 20 65 73 74 69 6d 61 74 65   double estimate
30e10 64 43 6f 73 74 3b 20 20 20 20 20 20 2f 2a 20 45  dCost;      /* E
30e20 73 74 69 6d 61 74 65 64 20 63 6f 73 74 20 6f 66  stimated cost of
30e30 20 75 73 69 6e 67 20 74 68 69 73 20 69 6e 64 65   using this inde
30e40 78 20 2a 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20  x */.};.#define 
30e50 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
30e60 53 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a  STRAINT_EQ    2.
30e70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
30e80 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
30e90 47 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  GT    4.#define 
30ea0 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
30eb0 53 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a  STRAINT_LE    8.
30ec0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
30ed0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
30ee0 4c 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65  LT    16.#define
30ef0 20 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f   SQLITE_INDEX_CO
30f00 4e 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33  NSTRAINT_GE    3
30f10 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
30f20 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
30f30 54 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a  T_MATCH 64../*.*
30f40 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69  * CAPI3REF: Regi
30f50 73 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54  ster A Virtual T
30f60 61 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74  able Implementat
30f70 69 6f 6e 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  ion.** EXPERIMEN
30f80 54 41 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  TAL.**.** ^This 
30f90 72 6f 75 74 69 6e 65 20 69 73 20 75 73 65 64 20  routine is used 
30fa0 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65  to register a ne
30fb0 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  w [virtual table
30fc0 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a   module] name..*
30fd0 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20  * ^Module names 
30fe0 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72  must be register
30ff0 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65  ed before.** cre
31000 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72  ating a new [vir
31010 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e  tual table] usin
31020 67 20 74 68 65 20 6d 6f 64 75 6c 65 2c 20 6f 72  g the module, or
31030 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a   before using a.
31040 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b  ** preexisting [
31050 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66  virtual table] f
31060 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a  or the module..*
31070 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65  *.** ^The module
31080 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74 65   name is registe
31090 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  red on the [data
310a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
310b0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
310c0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
310d0 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65  eter.  ^The name
310e0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
310f0 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a  s given by the .
31100 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
31110 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64  ter.  ^The third
31120 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
31130 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68  pointer to.** th
31140 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
31150 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
31160 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
31170 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a    ^The fourth.**
31180 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
31190 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e   arbitrary clien
311a0 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  t data pointer t
311b0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68  hat is passed th
311c0 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68  rough.** into th
311d0 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20  e [xCreate] and 
311e0 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f  [xConnect] metho
311f0 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61  ds of the virtua
31200 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a  l table module.*
31210 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72  * when a new vir
31220 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65  tual table is be
31230 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f   being created o
31240 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e  r reinitialized.
31250 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
31260 65 72 66 61 63 65 20 68 61 73 20 65 78 61 63 74  erface has exact
31270 6c 79 20 74 68 65 20 73 61 6d 65 20 65 66 66 65  ly the same effe
31280 63 74 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a  ct as calling.**
31290 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
312a0 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 20 77 69  _module_v2()] wi
312b0 74 68 20 61 20 4e 55 4c 4c 20 63 6c 69 65 6e 74  th a NULL client
312c0 20 64 61 74 61 20 64 65 73 74 72 75 63 74 6f 72   data destructor
312d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45  ..*/.SQLITE_EXPE
312e0 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c  RIMENTAL int sql
312f0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
31300 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
31310 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
31320 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65   /* SQLite conne
31330 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65  ction to registe
31340 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f  r module with */
31350 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
31360 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a  Name,         /*
31370 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64   Name of the mod
31380 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73  ule */.  const s
31390 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
313a0 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  ,   /* Methods f
313b0 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  or the module */
313c0 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74  .  void *pClient
313d0 44 61 74 61 20 20 20 20 20 20 20 20 20 20 2f 2a  Data          /*
313e0 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72   Client data for
313f0 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63   xCreate/xConnec
31400 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  t */.);../*.** C
31410 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
31420 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  r A Virtual Tabl
31430 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e Implementation
31440 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e 54 41 4c  .** EXPERIMENTAL
31450 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
31460 74 69 6e 65 20 69 73 20 69 64 65 6e 74 69 63 61  tine is identica
31470 6c 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  l to the [sqlite
31480 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
31490 29 5d 20 6d 65 74 68 6f 64 2c 0a 2a 2a 20 65 78  )] method,.** ex
314a0 63 65 70 74 20 74 68 61 74 20 69 74 20 68 61 73  cept that it has
314b0 20 61 6e 20 65 78 74 72 61 20 70 61 72 61 6d 65   an extra parame
314c0 74 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 0a  ter to specify .
314d0 2a 2a 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ** a destructor 
314e0 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 74 68 65  function for the
314f0 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f 69   client data poi
31500 6e 74 65 72 2e 20 20 5e 53 51 4c 69 74 65 20 77  nter.  ^SQLite w
31510 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ill.** invoke th
31520 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
31530 63 74 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20  ction (if it is 
31540 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53  not NULL) when S
31550 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67  QLite.** no long
31560 65 72 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c  er needs the pCl
31570 69 65 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72  ientData pointer
31580 2e 20 20 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  .  .*/.SQLITE_EX
31590 50 45 52 49 4d 45 4e 54 41 4c 20 69 6e 74 20 73  PERIMENTAL int s
315a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
315b0 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  dule_v2(.  sqlit
315c0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
315d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20        /* SQLite 
315e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
315f0 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69  gister module wi
31600 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  th */.  const ch
31610 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20  ar *zName,      
31620 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
31630 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f  e module */.  co
31640 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
31650 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68  le *p,   /* Meth
31660 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75  ods for the modu
31670 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43  le */.  void *pC
31680 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20 20  lientData,      
31690 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74     /* Client dat
316a0 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43  a for xCreate/xC
316b0 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64  onnect */.  void
316c0 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
316d0 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65  *)     /* Module
316e0 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63   destructor func
316f0 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  tion */.);../*.*
31700 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
31710 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e  ual Table Instan
31720 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ce Object.** KEY
31730 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
31740 74 61 62 0a 2a 2a 20 45 58 50 45 52 49 4d 45 4e  tab.** EXPERIMEN
31750 54 41 4c 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  TAL.**.** Every 
31760 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
31770 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74  odule] implement
31780 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62  ation uses a sub
31790 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69 73  class.** of this
317a0 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 73 63 72   object to descr
317b0 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61 72  ibe a particular
317c0 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20   instance.** of 
317d0 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
317e0 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63 6c  le].  Each subcl
317f0 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74  ass will.** be t
31800 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73  ailored to the s
31810 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
31820 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   the module impl
31830 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54  ementation..** T
31840 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68  he purpose of th
31850 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69 73  is superclass is
31860 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61   to define certa
31870 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20 61  in fields that a
31880 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20  re.** common to 
31890 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  all module imple
318a0 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  mentations..**.*
318b0 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 62 6c 65  * ^Virtual table
318c0 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65  s methods can se
318d0 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  t an error messa
318e0 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20  ge by assigning 
318f0 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61  a.** string obta
31900 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
31910 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f  e3_mprintf()] to
31920 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d   zErrMsg.  The m
31930 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20  ethod should.** 
31940 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20 61  take care that a
31950 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20  ny prior string 
31960 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63 61  is freed by a ca
31970 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ll to [sqlite3_f
31980 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20  ree()].** prior 
31990 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e  to assigning a n
319a0 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72  ew string to zEr
319b0 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 20 74 68  rMsg.  ^After th
319c0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a  e error message.
319d0 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64 20  ** is delivered 
319e0 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74  up to the client
319f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
31a00 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  e string will be
31a10 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
31a20 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69 74  * freed by sqlit
31a30 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68  e3_free() and th
31a40 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20  e zErrMsg field 
31a50 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a  will be zeroed..
31a60 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  */.struct sqlite
31a70 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74  3_vtab {.  const
31a80 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
31a90 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68  *pModule;  /* Th
31aa0 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69  e module for thi
31ab0 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  s virtual table 
31ac0 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20  */.  int nRef;  
31ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31ae0 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45       /* NO LONGE
31af0 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 72  R USED */.  char
31b00 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20   *zErrMsg;      
31b10 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
31b20 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f  rror message fro
31b30 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  m sqlite3_mprint
31b40 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  f() */.  /* Virt
31b50 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
31b60 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
31b70 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
31b80 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
31b90 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
31ba0 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
31bb0 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63  ble Cursor Objec
31bc0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
31bd0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
31be0 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c  or {virtual tabl
31bf0 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 20 45 58 50  e cursor}.** EXP
31c00 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20  ERIMENTAL.**.** 
31c10 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
31c20 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
31c30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
31c40 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
31c50 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
31c60 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65 73  structure to des
31c70 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74 68  cribe cursors th
31c80 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68  at point into th
31c90 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  e.** [virtual ta
31ca0 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73 65  ble] and are use
31cb0 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72  d.** to loop thr
31cc0 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61 6c  ough the virtual
31cd0 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73   table.  Cursors
31ce0 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
31cf0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
31d00 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20  e3_module.xOpen 
31d10 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  | xOpen] method 
31d20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e  of the module an
31d30 64 20 61 72 65 20 64 65 73 74 72 6f 79 65 64 0a  d are destroyed.
31d40 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ** by the [sqlit
31d50 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65  e3_module.xClose
31d60 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f   | xClose] metho
31d70 64 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20  d.  Cursors are 
31d80 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  used.** by the [
31d90 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74  xFilter], [xNext
31da0 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c  ], [xEof], [xCol
31db0 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69  umn], and [xRowi
31dc0 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  d] methods.** of
31dd0 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61   the module.  Ea
31de0 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  ch module implem
31df0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65  entation will de
31e00 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  fine.** the cont
31e10 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20  ent of a cursor 
31e20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75 69  structure to sui
31e30 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e  t its own needs.
31e40 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65  .**.** This supe
31e50 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e  rclass exists in
31e60 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65   order to define
31e70 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63   fields of the c
31e80 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72  ursor that.** ar
31e90 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20  e common to all 
31ea0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
31eb0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
31ec0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b  e3_vtab_cursor {
31ed0 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20  .  sqlite3_vtab 
31ee0 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20  *pVtab;      /* 
31ef0 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66  Virtual table of
31f00 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a   this cursor */.
31f10 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62    /* Virtual tab
31f20 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
31f30 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c  ns will typicall
31f40 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c  y add additional
31f50 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f   fields */.};../
31f60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
31f70 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d  eclare The Schem
31f80 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54  a Of A Virtual T
31f90 61 62 6c 65 0a 2a 2a 20 45 58 50 45 52 49 4d 45  able.** EXPERIME
31fa0 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  NTAL.**.** ^The 
31fb0 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78  [xCreate] and [x
31fc0 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73  Connect] methods
31fd0 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61   of a.** [virtua
31fe0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
31ff0 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66  call this interf
32000 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72  ace.** to declar
32010 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68  e the format (th
32020 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61  e names and data
32030 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  types of the col
32040 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20  umns) of.** the 
32050 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74  virtual tables t
32060 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a  hey implement..*
32070 2f 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  /.SQLITE_EXPERIM
32080 45 4e 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65  ENTAL int sqlite
32090 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73  3_declare_vtab(s
320a0 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
320b0 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a  har *zSQL);../*.
320c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65  ** CAPI3REF: Ove
320d0 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e  rload A Function
320e0 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54   For A Virtual T
320f0 61 62 6c 65 0a 2a 2a 20 45 58 50 45 52 49 4d 45  able.** EXPERIME
32100 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72  NTAL.**.** ^(Vir
32110 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20  tual tables can 
32120 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74  provide alternat
32130 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ive implementati
32140 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ons of functions
32150 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78  .** using the [x
32160 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65  FindFunction] me
32170 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72  thod of the [vir
32180 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
32190 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f  e].  .** But glo
321a0 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  bal versions of 
321b0 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a  those functions.
321c0 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e  ** must exist in
321d0 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65   order to be ove
321e0 72 6c 6f 61 64 65 64 2e 29 0a 2a 2a 0a 2a 2a 20  rloaded.).**.** 
321f0 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73  ^(This API makes
32200 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76   sure a global v
32210 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63  ersion of a func
32220 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74  tion with a part
32230 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61  icular.** name a
32240 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  nd number of par
32250 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20  ameters exists. 
32260 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63   If no such func
32270 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62  tion exists.** b
32280 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69  efore this API i
32290 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20  s called, a new 
322a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61  function is crea
322b0 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70  ted.)^  ^The imp
322c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
322d0 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  f the new functi
322e0 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73  on always causes
322f0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f   an exception to
32300 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a   be thrown.  So.
32310 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  ** the new funct
32320 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20  ion is not good 
32330 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20  for anything by 
32340 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c  itself.  Its onl
32350 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20  y.** purpose is 
32360 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c  to be a placehol
32370 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  der function tha
32380 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61  t can be overloa
32390 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72  ded.** by a [vir
323a0 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a  tual table]..*/.
323b0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
323c0 54 41 4c 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TAL int sqlite3_
323d0 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f  overload_functio
323e0 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73  n(sqlite3*, cons
323f0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d  t char *zFuncNam
32400 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f  e, int nArg);../
32410 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61  *.** The interfa
32420 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61  ce to the virtua
32430 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
32440 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20  m defined above 
32450 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61  (back up.** to a
32460 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61   comment remarka
32470 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74  bly similar to t
32480 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72  his one) is curr
32490 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
324a0 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
324b0 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
324c0 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
324d0 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
324e0 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
324f0 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
32500 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
32510 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
32520 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
32530 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
32540 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
32550 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
32560 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
32570 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
32580 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
32590 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
325a0 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
325b0 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
325c0 2a 0a 2a 2a 2a 2a 2a 2a 20 45 58 50 45 52 49 4d  *.****** EXPERIM
325d0 45 4e 54 41 4c 20 2d 20 73 75 62 6a 65 63 74 20  ENTAL - subject 
325e0 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
325f0 74 20 6e 6f 74 69 63 65 20 2a 2a 2a 2a 2a 2a 2a  t notice *******
32600 2a 2a 2a 2a 2a 2a 2a 0a 2a 2f 0a 0a 2f 2a 0a 2a  *******.*/../*.*
32610 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61  * CAPI3REF: A Ha
32620 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20  ndle To An Open 
32630 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  BLOB.** KEYWORDS
32640 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20  : {BLOB handle} 
32650 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a  {BLOB handles}.*
32660 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
32670 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
32680 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
32690 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68  en BLOB on which
326a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
326b0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
326c0 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63  ntal BLOB I/O] c
326d0 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e  an be performed.
326e0 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20 6f 66 20  .** ^Objects of 
326f0 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72  this type are cr
32700 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
32710 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a  3_blob_open()].*
32720 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20  * and destroyed 
32730 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
32740 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54  _close()]..** ^T
32750 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
32760 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71  _read()] and [sq
32770 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
32780 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
32790 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
327a0 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73   read or write s
327b0 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73  mall subsections
327c0 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a   of the BLOB..**
327d0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
327e0 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74  lob_bytes()] int
327f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
32800 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42  he size of the B
32810 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  LOB in bytes..*/
32820 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
32830 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
32840 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
32850 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
32860 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
32870 65 6d 65 6e 74 61 6c 20 49 2f 4f 20 7b 48 31 37  emental I/O {H17
32880 38 31 30 7d 20 3c 53 33 30 32 33 30 3e 0a 2a 2a  810} <S30230>.**
32890 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
328a0 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42  faces opens a [B
328b0 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e  LOB handle | han
328c0 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42  dle] to the BLOB
328d0 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72   located.** in r
328e0 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20  ow iRow, column 
328f0 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a  zColumn, table z
32900 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73  Table in databas
32910 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68  e zDb;.** in oth
32920 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61  er words, the sa
32930 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75  me BLOB that wou
32940 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20 62  ld be selected b
32950 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a  y:.**.** <pre>.*
32960 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f  *     SELECT zCo
32970 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54  lumn FROM zDb.zT
32980 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69  able WHERE [rowi
32990 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f  d] = iRow;.** </
329a0 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  pre>)^.**.** ^If
329b0 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
329c0 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f  eter is non-zero
329d0 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20  , then the BLOB 
329e0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
329f0 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20  ad.** and write 
32a00 61 63 63 65 73 73 2e 20 5e 49 66 20 69 74 20 69  access. ^If it i
32a10 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42  s zero, the BLOB
32a20 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
32a30 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 5e  ead access..** ^
32a40 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  It is not possib
32a50 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c  le to open a col
32a60 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74  umn that is part
32a70 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f 72 20   of an index or 
32a80 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20  primary .** key 
32a90 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e 49 66  for writing. ^If
32aa0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
32ab0 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65 20 65  nstraints] are e
32ac0 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a  nabled, it is .*
32ad0 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  * not possible t
32ae0 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20  o open a column 
32af0 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20  that is part of 
32b00 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f  a [child key] fo
32b10 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  r writing..**.**
32b20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
32b30 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73  database name is
32b40 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d   not the filenam
32b50 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a  e that contains.
32b60 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
32b70 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20 73  but rather the s
32b80 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20  ymbolic name of 
32b90 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68 61  the database tha
32ba0 74 0a 2a 2a 20 61 70 70 65 61 72 73 20 61 66 74  t.** appears aft
32bb0 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72  er the AS keywor
32bc0 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  d when the datab
32bd0 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64  ase is connected
32be0 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e   using [ATTACH].
32bf0 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61 69  .** ^For the mai
32c00 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  n database file,
32c10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
32c20 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a  me is "main"..**
32c30 20 5e 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65   ^For TEMP table
32c40 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20  s, the database 
32c50 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a  name is "temp"..
32c60 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65  **.** ^(On succe
32c70 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  ss, [SQLITE_OK] 
32c80 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20  is returned and 
32c90 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61  the new [BLOB ha
32ca0 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e  ndle] is written
32cb0 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20  .** to *ppBlob. 
32cc0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
32cd0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
32ce0 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f  urned and *ppBlo
32cf0 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62  b is set.** to b
32d00 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72  e a null pointer
32d10 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .)^.** ^This fun
32d20 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b  ction sets the [
32d30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32d40 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20  ion] error code 
32d50 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61  and message.** a
32d60 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73  ccessible via [s
32d70 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
32d80 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65  ] and [sqlite3_e
32d90 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 6c  rrmsg()] and rel
32da0 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ated.** function
32db0 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  s. ^Note that th
32dc0 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 62  e *ppBlob variab
32dd0 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e 69  le is always ini
32de0 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a  tialized in a.**
32df0 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20   way that makes 
32e00 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b  it safe to invok
32e10 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
32e20 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42  close()] on *ppB
32e30 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  lob.** regardles
32e40 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
32e50 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
32e60 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a  his routine..**.
32e70 2a 2a 20 5e 28 49 66 20 74 68 65 20 72 6f 77 20  ** ^(If the row 
32e80 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64  that a BLOB hand
32e90 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
32ea0 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a  modified by an.*
32eb0 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c  * [UPDATE], [DEL
32ec0 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20  ETE], or by [ON 
32ed0 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65  CONFLICT] side-e
32ee0 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74  ffects.** then t
32ef0 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69  he BLOB handle i
32f00 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70  s marked as "exp
32f10 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69  ired"..** This i
32f20 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f  s true if any co
32f30 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20  lumn of the row 
32f40 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e  is changed, even
32f50 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68   a column.** oth
32f60 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  er than the one 
32f70 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  the BLOB handle 
32f80 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a  is open on.)^.**
32f90 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69   ^Calls to [sqli
32fa0 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d  te3_blob_read()]
32fb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c   and [sqlite3_bl
32fc0 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a  ob_write()] for.
32fd0 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f  ** a expired BLO
32fe0 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69  B handle fail wi
32ff0 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64  th an return cod
33000 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f  e of [SQLITE_ABO
33010 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67 65  RT]..** ^(Change
33020 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61  s written into a
33030 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74   BLOB prior to t
33040 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67  he BLOB expiring
33050 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c   are not.** roll
33060 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 69  back by the expi
33070 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c  ration of the BL
33080 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65  OB.  Such change
33090 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
330a0 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74  y.** commit if t
330b0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  he transaction c
330c0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
330d0 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20  letion.)^.**.** 
330e0 5e 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65  ^Use the [sqlite
330f0 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
33100 69 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65 74  interface to det
33110 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20  ermine the size 
33120 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64  of.** the opened
33130 20 62 6c 6f 62 2e 20 20 5e 54 68 65 20 73 69 7a   blob.  ^The siz
33140 65 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20  e of a blob may 
33150 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 62  not be changed b
33160 79 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  y this.** interf
33170 61 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55  ace.  Use the [U
33180 50 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61  PDATE] SQL comma
33190 6e 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  nd to change the
331a0 20 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c   size of a.** bl
331b0 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ob..**.** ^The [
331c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
331d0 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71  oblob()] and [sq
331e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
331f0 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66 61  oblob()] interfa
33200 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62  ces.** and the b
33210 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f  uilt-in [zeroblo
33220 62 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  b] SQL function 
33230 63 61 6e 20 62 65 20 75 73 65 64 2c 20 69 66 20  can be used, if 
33240 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63  desired,.** to c
33250 72 65 61 74 65 20 61 6e 20 65 6d 70 74 79 2c 20  reate an empty, 
33260 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62  zero-filled blob
33270 20 69 6e 20 77 68 69 63 68 20 74 6f 20 72 65 61   in which to rea
33280 64 20 6f 72 20 77 72 69 74 65 20 75 73 69 6e 67  d or write using
33290 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61  .** this interfa
332a0 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f  ce..**.** To avo
332b0 69 64 20 61 20 72 65 73 6f 75 72 63 65 20 6c 65  id a resource le
332c0 61 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e 20 5b  ak, every open [
332d0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f  BLOB handle] sho
332e0 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a  uld eventually.*
332f0 2a 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  * be released by
33300 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
33310 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
33320 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
33330 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73  3_blob_open(.  s
33340 71 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74  qlite3*,.  const
33350 20 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f   char *zDb,.  co
33360 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
33370 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
33380 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74  zColumn,.  sqlit
33390 65 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20  e3_int64 iRow,. 
333a0 20 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71   int flags,.  sq
333b0 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42  lite3_blob **ppB
333c0 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lob.);../*.** CA
333d0 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20  PI3REF: Close A 
333e0 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  BLOB Handle.**.*
333f0 2a 20 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65  * ^Closes an ope
33400 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e  n [BLOB handle].
33410 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20  .**.** ^Closing 
33420 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75  a BLOB shall cau
33430 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  se the current t
33440 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f  ransaction to co
33450 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65  mmit.** if there
33460 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c   are no other BL
33470 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20  OBs, no pending 
33480 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
33490 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20  nts, and the.** 
334a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
334b0 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63  ion is in [autoc
334c0 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20  ommit mode]..** 
334d0 5e 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77  ^If any writes w
334e0 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20  ere made to the 
334f0 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74  BLOB, they might
33500 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68   be held in cach
33510 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63  e.** until the c
33520 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69  lose operation i
33530 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e  f they will fit.
33540 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67  .**.** ^(Closing
33550 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20   the BLOB often 
33560 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67  forces the chang
33570 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73  es.** out to dis
33580 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20  k and so if any 
33590 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72  I/O errors occur
335a0 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65  , they will like
335b0 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74  ly occur.** at t
335c0 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  he time when the
335d0 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e   BLOB is closed.
335e0 20 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61    Any errors tha
335f0 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a  t occur during.*
33600 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65  * closing are re
33610 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d  ported as a non-
33620 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75  zero return valu
33630 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  e.)^.**.** ^(The
33640 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20   BLOB is closed 
33650 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e  unconditionally.
33660 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72    Even if this r
33670 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a  outine returns.*
33680 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c  * an error code,
33690 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69   the BLOB is sti
336a0 6c 6c 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a  ll closed.)^.**.
336b0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
336c0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
336d0 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73 75  null pointer (su
336e0 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72  ch as would be r
336f0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61 20  eturned.** by a 
33700 66 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b  failed call to [
33710 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
33720 6e 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c  n()]) is a harml
33730 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e  ess no-op..*/.in
33740 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63  t sqlite3_blob_c
33750 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  lose(sqlite3_blo
33760 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
33770 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68  I3REF: Return Th
33780 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65  e Size Of An Ope
33790 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65  n BLOB.**.** ^Re
337a0 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69  turns the size i
337b0 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42  n bytes of the B
337c0 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 76  LOB accessible v
337d0 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65  ia the .** succe
337e0 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b  ssfully opened [
337f0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20  BLOB handle] in 
33800 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  its only argumen
33810 74 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 72  t.  ^The.** incr
33820 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f  emental blob I/O
33830 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e   routines can on
33840 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77  ly read or overw
33850 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a  riting existing.
33860 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b  ** blob content;
33870 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61   they cannot cha
33880 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  nge the size of 
33890 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68  a blob..**.** Th
338a0 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
338b0 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42  works on a [BLOB
338c0 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68   handle] which h
338d0 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a  as been created.
338e0 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75  ** by a prior su
338f0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
33900 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
33910 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68  pen()] and which
33920 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e   has not.** been
33930 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69   closed by [sqli
33940 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
33950 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20  ].  Passing any 
33960 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e  other pointer in
33970 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74  .** to this rout
33980 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ine results in u
33990 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
339a0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
339b0 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69  e behavior..*/.i
339c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
339d0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c  bytes(sqlite3_bl
339e0 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
339f0 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 74  PI3REF: Read Dat
33a00 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e  a From A BLOB In
33a10 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a  crementally.**.*
33a20 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f  * ^(This functio
33a30 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61  n is used to rea
33a40 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f  d data from an o
33a50 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  pen [BLOB handle
33a60 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c  ] into a.** call
33a70 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66  er-supplied buff
33a80 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64  er. N bytes of d
33a90 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69  ata are copied i
33aa0 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  nto buffer Z.** 
33ab0 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c  from the open BL
33ac0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
33ad0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 29  offset iOffset.)
33ae0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66 73  ^.**.** ^If offs
33af0 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65  et iOffset is le
33b00 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20  ss than N bytes 
33b10 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20  from the end of 
33b20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51  the BLOB,.** [SQ
33b30 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
33b40 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
33b50 61 74 61 20 69 73 20 72 65 61 64 2e 20 20 5e 49  ata is read.  ^I
33b60 66 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69  f N or iOffset i
33b70 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a  s.** less than z
33b80 65 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ero, [SQLITE_ERR
33b90 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
33ba0 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72  and no data is r
33bb0 65 61 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 69 7a  ead..** ^The siz
33bc0 65 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 28 61  e of the blob (a
33bd0 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78  nd hence the max
33be0 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b  imum value of N+
33bf0 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20  iOffset).** can 
33c00 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
33c10 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
33c20 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
33c30 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
33c40 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72  ^An attempt to r
33c50 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70 69  ead from an expi
33c60 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  red [BLOB handle
33c70 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a  ] fails with an.
33c80 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66  ** error code of
33c90 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
33ca0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63  .**.** ^(On succ
33cb0 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f  ess, sqlite3_blo
33cc0 62 5f 72 65 61 64 28 29 20 72 65 74 75 72 6e 73  b_read() returns
33cd0 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f   SQLITE_OK..** O
33ce0 74 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72  therwise, an [er
33cf0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20  ror code] or an 
33d00 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
33d10 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
33d20 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  d.)^.**.** This 
33d30 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72  routine only wor
33d40 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61  ks on a [BLOB ha
33d50 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20  ndle] which has 
33d60 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20  been created.** 
33d70 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  by a prior succe
33d80 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
33d90 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
33da0 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61  ()] and which ha
33db0 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c  s not.** been cl
33dc0 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
33dd0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20  _blob_close()]. 
33de0 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68   Passing any oth
33df0 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a  er pointer in.**
33e00 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
33e10 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
33e20 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
33e30 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ly undesirable b
33e40 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53  ehavior..**.** S
33e50 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
33e60 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e  3_blob_write()].
33e70 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33e80 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65  blob_read(sqlite
33e90 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a  3_blob *, void *
33ea0 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f  Z, int N, int iO
33eb0 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ffset);../*.** C
33ec0 41 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 44  API3REF: Write D
33ed0 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20  ata Into A BLOB 
33ee0 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a  Incrementally.**
33ef0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
33f00 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72  on is used to wr
33f10 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e  ite data into an
33f20 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
33f30 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61  le] from a.** ca
33f40 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75  ller-supplied bu
33f50 66 66 65 72 2e 20 5e 4e 20 62 79 74 65 73 20 6f  ffer. ^N bytes o
33f60 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65  f data are copie
33f70 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65  d from the buffe
33f80 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  r Z.** into the 
33f90 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74  open BLOB, start
33fa0 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f  ing at offset iO
33fb0 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ffset..**.** ^If
33fc0 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   the [BLOB handl
33fd0 65 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  e] passed as the
33fe0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
33ff0 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66  was not opened f
34000 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74  or.** writing (t
34010 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
34020 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
34030 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20  lob_open()] was 
34040 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66  zero),.** this f
34050 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
34060 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  [SQLITE_READONLY
34070 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ]..**.** ^This f
34080 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79  unction may only
34090 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74   modify the cont
340a0 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ents of the BLOB
340b0 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70  ; it is.** not p
340c0 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65  ossible to incre
340d0 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ase the size of 
340e0 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 69  a BLOB using thi
340f0 73 20 41 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66  s API..** ^If of
34100 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20  fset iOffset is 
34110 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65  less than N byte
34120 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f  s from the end o
34130 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b  f the BLOB,.** [
34140 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
34150 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
34160 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e   data is written
34170 2e 20 20 5e 49 66 20 4e 20 69 73 0a 2a 2a 20 6c  .  ^If N is.** l
34180 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53  ess than zero [S
34190 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
341a0 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
341b0 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e  data is written.
341c0 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20  .** The size of 
341d0 74 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 65  the BLOB (and he
341e0 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  nce the maximum 
341f0 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73  value of N+iOffs
34200 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65  et).** can be de
34210 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74  termined using t
34220 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
34230 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
34240 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ace..**.** ^An a
34250 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
34260 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42  to an expired [B
34270 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c  LOB handle] fail
34280 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72  s with an.** err
34290 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
342a0 54 45 5f 41 42 4f 52 54 5d 2e 20 20 5e 57 72 69  TE_ABORT].  ^Wri
342b0 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  tes to the BLOB 
342c0 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a  that occurred.**
342d0 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f   before the [BLO
342e0 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65  B handle] expire
342f0 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64  d are not rolled
34300 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20   back by the.** 
34310 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68  expiration of th
34320 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68  e handle, though
34330 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65   of course those
34340 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a   changes might.*
34350 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72  * have been over
34360 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 73  written by the s
34370 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78  tatement that ex
34380 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68  pired the BLOB h
34390 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f  andle.** or by o
343a0 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74  ther independent
343b0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
343c0 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c  ** ^(On success,
343d0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72   sqlite3_blob_wr
343e0 69 74 65 28 29 20 72 65 74 75 72 6e 73 20 53 51  ite() returns SQ
343f0 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65  LITE_OK..** Othe
34400 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f  rwise, an  [erro
34410 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65  r code] or an [e
34420 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
34430 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
34440 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  )^.**.** This ro
34450 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73  utine only works
34460 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64   on a [BLOB hand
34470 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65  le] which has be
34480 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79  en created.** by
34490 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73   a prior success
344a0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
344b0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
344c0 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20  ] and which has 
344d0 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73  not.** been clos
344e0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
344f0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50  lob_close()].  P
34500 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  assing any other
34510 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74   pointer in.** t
34520 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  o this routine r
34530 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
34540 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
34550 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
34560 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  avior..**.** See
34570 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
34580 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2f  blob_read()]..*/
34590 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
345a0 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f  b_write(sqlite3_
345b0 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f  blob *, const vo
345c0 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e  id *z, int n, in
345d0 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a  t iOffset);../*.
345e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
345f0 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d  tual File System
34600 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41   Objects.**.** A
34610 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73   virtual filesys
34620 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20  tem (VFS) is an 
34630 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
34640 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ject.** that SQL
34650 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65  ite uses to inte
34660 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65  ract.** with the
34670 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
34680 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d  ating system.  M
34690 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64  ost SQLite build
346a0 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a  s come with a.**
346b0 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20   single default 
346c0 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72  VFS that is appr
346d0 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20  opriate for the 
346e0 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
346f0 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20  * New VFSes can 
34700 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  be registered an
34710 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73  d existing VFSes
34720 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74   can be unregist
34730 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c  ered..** The fol
34740 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
34750 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a  s are provided..
34760 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34770 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e  e3_vfs_find() in
34780 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
34790 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56  a pointer to a V
347a0 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  FS given its nam
347b0 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65  e..** ^Names are
347c0 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e   case sensitive.
347d0 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20 7a  .** ^Names are z
347e0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
347f0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
34800 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f   ^If there is no
34810 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70   match, a NULL p
34820 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
34830 65 64 2e 0a 2a 2a 20 5e 49 66 20 7a 56 66 73 4e  ed..** ^If zVfsN
34840 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ame is NULL then
34850 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
34860 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
34870 0a 2a 2a 20 5e 4e 65 77 20 56 46 53 65 73 20 61  .** ^New VFSes a
34880 72 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  re registered wi
34890 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  th sqlite3_vfs_r
348a0 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 5e 45  egister()..** ^E
348b0 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f  ach new VFS beco
348c0 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20  mes the default 
348d0 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44  VFS if the makeD
348e0 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e  flt flag is set.
348f0 0a 2a 2a 20 5e 54 68 65 20 73 61 6d 65 20 56 46  .** ^The same VF
34900 53 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  S can be registe
34910 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
34920 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72  es without injur
34930 79 2e 0a 2a 2a 20 5e 54 6f 20 6d 61 6b 65 20 61  y..** ^To make a
34940 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69  n existing VFS i
34950 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20  nto the default 
34960 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74  VFS, register it
34970 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74   again.** with t
34980 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67  he makeDflt flag
34990 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69   set.  If two di
349a0 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 69  fferent VFSes wi
349b0 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e  th the.** same n
349c0 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 72  ame are register
349d0 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ed, the behavior
349e0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
349f0 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72  If a.** VFS is r
34a00 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61  egistered with a
34a10 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55   name that is NU
34a20 4c 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73  LL or an empty s
34a30 74 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74  tring,.** then t
34a40 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
34a50 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
34a60 5e 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46  ^Unregister a VF
34a70 53 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74  S with the sqlit
34a80 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
34a90 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  r() interface..*
34aa0 2a 20 5e 28 49 66 20 74 68 65 20 64 65 66 61 75  * ^(If the defau
34ab0 6c 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69  lt VFS is unregi
34ac0 73 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20  stered, another 
34ad0 56 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73  VFS is chosen as
34ae0 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e  .** the default.
34af0 20 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72    The choice for
34b00 20 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20   the new VFS is 
34b10 61 72 62 69 74 72 61 72 79 2e 29 5e 0a 2a 2f 0a  arbitrary.)^.*/.
34b20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c  sqlite3_vfs *sql
34b30 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f  ite3_vfs_find(co
34b40 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61  nst char *zVfsNa
34b50 6d 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  me);.int sqlite3
34b60 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71  _vfs_register(sq
34b70 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
34b80 6d 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73  makeDflt);.int s
34b90 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
34ba0 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66  ister(sqlite3_vf
34bb0 73 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s*);../*.** CAPI
34bc0 33 52 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a  3REF: Mutexes.**
34bd0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
34be0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72  ore uses these r
34bf0 6f 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65  outines for thre
34c00 61 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a  ad.** synchroniz
34c10 61 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68  ation. Though th
34c20 65 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ey are intended 
34c30 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20  for internal.** 
34c40 75 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63  use by SQLite, c
34c50 6f 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  ode that links a
34c60 67 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73  gainst SQLite is
34c70 0a 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f  .** permitted to
34c80 20 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73   use any of thes
34c90 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
34ca0 2a 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75  * The SQLite sou
34cb0 72 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e  rce code contain
34cc0 73 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  s multiple imple
34cd0 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66  mentations.** of
34ce0 20 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75   these mutex rou
34cf0 74 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f  tines.  An appro
34d00 70 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74  priate implement
34d10 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65  ation.** is sele
34d20 63 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  cted automatical
34d30 6c 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ly at compile-ti
34d40 6d 65 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  me.  ^(The follo
34d50 77 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  wing.** implemen
34d60 74 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69  tations are avai
34d70 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c  lable in the SQL
34d80 69 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20  ite core:.**.** 
34d90 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53  <ul>.** <li>   S
34da0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a  QLITE_MUTEX_OS2.
34db0 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45  ** <li>   SQLITE
34dc0 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a  _MUTEX_PTHREAD.*
34dd0 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
34de0 4d 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69  MUTEX_W32.** <li
34df0 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  >   SQLITE_MUTEX
34e00 5f 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _NOOP.** </ul>)^
34e10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  .**.** ^The SQLI
34e20 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d  TE_MUTEX_NOOP im
34e30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
34e40 61 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65  a set of routine
34e50 73 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  s.** that does n
34e60 6f 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61  o real locking a
34e70 6e 64 20 69 73 20 61 70 70 72 6f 70 72 69 61 74  nd is appropriat
34e80 65 20 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20  e for use in.** 
34e90 61 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  a single-threade
34ea0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  d application.  
34eb0 5e 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45  ^The SQLITE_MUTE
34ec0 58 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45  X_OS2,.** SQLITE
34ed0 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c 20  _MUTEX_PTHREAD, 
34ee0 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  and SQLITE_MUTEX
34ef0 5f 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74  _W32 implementat
34f00 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70 72  ions.** are appr
34f10 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20  opriate for use 
34f20 6f 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61  on OS/2, Unix, a
34f30 6e 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a  nd Windows..**.*
34f40 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 69 73  * ^(If SQLite is
34f50 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
34f60 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
34f70 41 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 73  APPDEF preproces
34f80 73 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66  sor.** macro def
34f90 69 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 51  ined (with "-DSQ
34fa0 4c 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45  LITE_MUTEX_APPDE
34fb0 46 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d  F=1"), then no m
34fc0 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  utex.** implemen
34fd0 74 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64  tation is includ
34fe0 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72  ed with the libr
34ff0 61 72 79 2e 20 49 6e 20 74 68 69 73 20 63 61 73  ary. In this cas
35000 65 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  e the.** applica
35010 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
35020 20 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 78 20   a custom mutex 
35030 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
35040 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
35050 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
35060 5d 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65 20  ] option of the 
35070 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
35080 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66   function.** bef
35090 6f 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69  ore calling sqli
350a0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
350b0 20 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 70 75   or any other pu
350c0 62 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a  blic sqlite3_.**
350d0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63   function that c
350e0 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
350f0 74 69 61 6c 69 7a 65 28 29 2e 29 5e 0a 2a 2a 0a  tialize().)^.**.
35100 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35110 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f  mutex_alloc() ro
35120 75 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20  utine allocates 
35130 61 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61  a new.** mutex a
35140 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
35150 6e 74 65 72 20 74 6f 20 69 74 2e 20 5e 49 66 20  nter to it. ^If 
35160 69 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a  it returns NULL.
35170 2a 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ** that means th
35180 61 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64  at a mutex could
35190 20 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65   not be allocate
351a0 64 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 77  d.  ^SQLite.** w
351b0 69 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73  ill unwind its s
351c0 74 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20  tack and return 
351d0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 28 54 68 65  an error.  ^(The
351e0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
351f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
35200 6c 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20  loc() is one of 
35210 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  these integer co
35220 6e 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  nstants:.**.** <
35230 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
35240 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a  ITE_MUTEX_FAST.*
35250 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
35260 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a  UTEX_RECURSIVE.*
35270 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
35280 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
35290 45 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ER.** <li>  SQLI
352a0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
352b0 4d 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  MEM.** <li>  SQL
352c0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
352d0 5f 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53  _MEM2.** <li>  S
352e0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
352f0 49 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20  IC_PRNG.** <li> 
35300 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
35310 41 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e  ATIC_LRU.** <li>
35320 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53    SQLITE_MUTEX_S
35330 54 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f  TATIC_LRU2.** </
35340 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ul>)^.**.** ^The
35350 20 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74   first two const
35360 61 6e 74 73 20 28 53 51 4c 49 54 45 5f 4d 55 54  ants (SQLITE_MUT
35370 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c 49  EX_FAST and SQLI
35380 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
35390 56 45 29 0a 2a 2a 20 63 61 75 73 65 20 73 71 6c  VE).** cause sql
353a0 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
353b0 28 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20  () to create.** 
353c0 61 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 5e 54  a new mutex.  ^T
353d0 68 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20  he new mutex is 
353e0 72 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53  recursive when S
353f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
35400 52 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64  RSIVE.** is used
35410 20 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61   but not necessa
35420 72 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c  rily so when SQL
35430 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69  ITE_MUTEX_FAST i
35440 73 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  s used..** The m
35450 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74  utex implementat
35460 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
35470 64 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74  d to make a dist
35480 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
35490 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  en SQLITE_MUTEX_
354a0 52 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51  RECURSIVE and SQ
354b0 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
354c0 69 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  if it does.** no
354d0 74 20 77 61 6e 74 20 74 6f 2e 20 20 5e 53 51 4c  t want to.  ^SQL
354e0 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65  ite will only re
354f0 71 75 65 73 74 20 61 20 72 65 63 75 72 73 69 76  quest a recursiv
35500 65 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61  e mutex in.** ca
35510 73 65 73 20 77 68 65 72 65 20 69 74 20 72 65 61  ses where it rea
35520 6c 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20  lly needs one.  
35530 5e 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e  ^If a faster non
35540 2d 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78  -recursive mutex
35550 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
35560 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
35570 6f 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74  on the host plat
35580 66 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20  form, the mutex 
35590 73 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67  subsystem.** mig
355a0 68 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61  ht return such a
355b0 20 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e   mutex in respon
355c0 73 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54  se to SQLITE_MUT
355d0 45 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 5e  EX_FAST..**.** ^
355e0 54 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65  The other allowe
355f0 64 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  d parameters to 
35600 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
35610 6c 6f 63 28 29 20 28 61 6e 79 74 68 69 6e 67 20  loc() (anything 
35620 6f 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 53 51  other.** than SQ
35630 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
35640 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  and SQLITE_MUTEX
35650 5f 52 45 43 55 52 53 49 56 45 29 20 65 61 63 68  _RECURSIVE) each
35660 20 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69   return.** a poi
35670 6e 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63  nter to a static
35680 20 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74   preexisting mut
35690 65 78 2e 20 20 5e 53 69 78 20 73 74 61 74 69 63  ex.  ^Six static
356a0 20 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20   mutexes are.** 
356b0 75 73 65 64 20 62 79 20 74 68 65 20 63 75 72 72  used by the curr
356c0 65 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53  ent version of S
356d0 51 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 76  QLite.  Future v
356e0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
356f0 65 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64  e.** may add add
35700 69 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d  itional static m
35710 75 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 20  utexes.  Static 
35720 6d 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 20  mutexes are for 
35730 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20  internal.** use 
35740 62 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20  by SQLite only. 
35750 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
35760 61 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75  at use SQLite mu
35770 74 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  texes should.** 
35780 75 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e  use only the dyn
35790 61 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 74  amic mutexes ret
357a0 75 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f  urned by SQLITE_
357b0 4d 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a  MUTEX_FAST or.**
357c0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
357d0 43 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 5e  CURSIVE..**.** ^
357e0 4e 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65  Note that if one
357f0 20 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20   of the dynamic 
35800 6d 75 74 65 78 20 70 61 72 61 6d 65 74 65 72 73  mutex parameters
35810 20 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46   (SQLITE_MUTEX_F
35820 41 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45  AST.** or SQLITE
35830 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
35840 29 20 69 73 20 75 73 65 64 20 74 68 65 6e 20 73  ) is used then s
35850 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
35860 6f 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  oc().** returns 
35870 61 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65  a different mute
35880 78 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e  x on every call.
35890 20 20 5e 42 75 74 20 66 6f 72 20 74 68 65 20 73    ^But for the s
358a0 74 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74  tatic.** mutex t
358b0 79 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d  ypes, the same m
358c0 75 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 64  utex is returned
358d0 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74   on every call t
358e0 68 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73  hat has.** the s
358f0 61 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e  ame type number.
35900 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35910 74 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29  te3_mutex_free()
35920 20 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63   routine dealloc
35930 61 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c  ates a previousl
35940 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64  y.** allocated d
35950 79 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 20 5e  ynamic mutex.  ^
35960 53 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75  SQLite is carefu
35970 6c 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20  l to deallocate 
35980 65 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63  every.** dynamic
35990 20 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61   mutex that it a
359a0 6c 6c 6f 63 61 74 65 73 2e 20 20 54 68 65 20 64  llocates.  The d
359b0 79 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d  ynamic mutexes m
359c0 75 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a  ust not be in.**
359d0 20 75 73 65 20 77 68 65 6e 20 74 68 65 79 20 61   use when they a
359e0 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20  re deallocated. 
359f0 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64   Attempting to d
35a00 65 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74  eallocate a stat
35a10 69 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75  ic.** mutex resu
35a20 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
35a30 20 62 65 68 61 76 69 6f 72 2e 20 20 5e 53 51 4c   behavior.  ^SQL
35a40 69 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f  ite never deallo
35a50 63 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69  cates.** a stati
35a60 63 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e  c mutex..**.** ^
35a70 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
35a80 78 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71  x_enter() and sq
35a90 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
35aa0 29 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  ) routines attem
35ab0 70 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61  pt.** to enter a
35ac0 20 6d 75 74 65 78 2e 20 20 5e 49 66 20 61 6e 6f   mutex.  ^If ano
35ad0 74 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61  ther thread is a
35ae0 6c 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68  lready within th
35af0 65 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69  e mutex,.** sqli
35b00 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
35b10 29 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64  ) will block and
35b20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
35b30 72 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ry() will return
35b40 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  .** SQLITE_BUSY.
35b50 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d    ^The sqlite3_m
35b60 75 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72  utex_try() inter
35b70 66 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51  face returns [SQ
35b80 4c 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e  LITE_OK].** upon
35b90 20 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72   successful entr
35ba0 79 2e 20 20 5e 28 4d 75 74 65 78 65 73 20 63 72  y.  ^(Mutexes cr
35bb0 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53  eated using.** S
35bc0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
35bd0 52 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e 74  RSIVE can be ent
35be0 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
35bf0 6d 65 73 20 62 79 20 74 68 65 20 73 61 6d 65 20  mes by the same 
35c00 74 68 72 65 61 64 2e 0a 2a 2a 20 49 6e 20 73 75  thread..** In su
35c10 63 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a  ch cases the,.**
35c20 20 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65   mutex must be e
35c30 78 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e  xited an equal n
35c40 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62  umber of times b
35c50 65 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68  efore another th
35c60 72 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65  read.** can ente
35c70 72 2e 29 5e 20 20 5e 28 49 66 20 74 68 65 20 73  r.)^  ^(If the s
35c80 61 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73  ame thread tries
35c90 20 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74   to enter any ot
35ca0 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d  her.** kind of m
35cb0 75 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f  utex more than o
35cc0 6e 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f  nce, the behavio
35cd0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
35ce0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
35cf0 65 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20  ever exhibit.** 
35d00 73 75 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e  such behavior in
35d10 20 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20   its own use of 
35d20 6d 75 74 65 78 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a  mutexes.)^.**.**
35d30 20 5e 28 53 6f 6d 65 20 73 79 73 74 65 6d 73 20   ^(Some systems 
35d40 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57 69  (for example, Wi
35d50 6e 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f 74  ndows 95) do not
35d60 20 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70 65   support the ope
35d70 72 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ration.** implem
35d80 65 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  ented by sqlite3
35d90 5f 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f  _mutex_try().  O
35da0 6e 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c  n those systems,
35db0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
35dc0 72 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77  ry().** will alw
35dd0 61 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54  ays return SQLIT
35de0 45 5f 42 55 53 59 2e 20 20 54 68 65 20 53 51 4c  E_BUSY.  The SQL
35df0 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76  ite core only ev
35e00 65 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74  er uses.** sqlit
35e10 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61  e3_mutex_try() a
35e20 73 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f  s an optimizatio
35e30 6e 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 63  n so this is acc
35e40 65 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72  eptable behavior
35e50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
35e60 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
35e70 76 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69  ve() routine exi
35e80 74 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20  ts a mutex that 
35e90 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
35ea0 79 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65  y entered by the
35eb0 20 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 20   same thread.   
35ec0 5e 28 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  ^(The behavior.*
35ed0 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69  * is undefined i
35ee0 66 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e  f the mutex is n
35ef0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ot currently ent
35f00 65 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63  ered by the.** c
35f10 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72  alling thread or
35f20 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
35f30 79 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51  y allocated.  SQ
35f40 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76  Lite will.** nev
35f50 65 72 20 64 6f 20 65 69 74 68 65 72 2e 29 5e 0a  er do either.)^.
35f60 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72  **.** ^If the ar
35f70 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
35f80 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 2c  3_mutex_enter(),
35f90 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
35fa0 72 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69  ry(), or.** sqli
35fb0 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28  te3_mutex_leave(
35fc0 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) is a NULL poin
35fd0 74 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68  ter, then all th
35fe0 72 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ree routines.** 
35ff0 62 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73  behave as no-ops
36000 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
36010 3a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  : [sqlite3_mutex
36020 5f 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71  _held()] and [sq
36030 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
36040 65 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74  eld()]..*/.sqlit
36050 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65  e3_mutex *sqlite
36060 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e  3_mutex_alloc(in
36070 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
36080 5f 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c 69  _mutex_free(sqli
36090 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69  te3_mutex*);.voi
360a0 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
360b0 65 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d 75  enter(sqlite3_mu
360c0 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  tex*);.int sqlit
360d0 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 6c  e3_mutex_try(sql
360e0 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f  ite3_mutex*);.vo
360f0 69 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  id sqlite3_mutex
36100 5f 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f 6d  _leave(sqlite3_m
36110 75 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  utex*);../*.** C
36120 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 4d  API3REF: Mutex M
36130 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
36140 20 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 2a 2a   EXPERIMENTAL.**
36150 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
36160 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
36170 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 6c 6f  e defines the lo
36180 77 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65 73  w-level routines
36190 0a 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f  .** used to allo
361a0 63 61 74 65 20 61 6e 64 20 75 73 65 20 6d 75 74  cate and use mut
361b0 65 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61  exes..**.** Usua
361c0 6c 6c 79 2c 20 74 68 65 20 64 65 66 61 75 6c 74  lly, the default
361d0 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
361e0 61 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 20  ations provided 
361f0 62 79 20 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a  by SQLite are.**
36200 20 73 75 66 66 69 63 69 65 6e 74 2c 20 68 6f 77   sufficient, how
36210 65 76 65 72 20 74 68 65 20 75 73 65 72 20 68 61  ever the user ha
36220 73 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20  s the option of 
36230 73 75 62 73 74 69 74 75 74 69 6e 67 20 61 20 63  substituting a c
36240 75 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ustom.** impleme
36250 6e 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 65 63  ntation for spec
36260 69 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65  ialized deployme
36270 6e 74 73 20 6f 72 20 73 79 73 74 65 6d 73 20 66  nts or systems f
36280 6f 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 0a  or which SQLite.
36290 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76  ** does not prov
362a0 69 64 65 20 61 20 73 75 69 74 61 62 6c 65 20 69  ide a suitable i
362b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49  mplementation. I
362c0 6e 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65  n this case, the
362d0 20 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 65 73   user.** creates
362e0 20 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20 61   and populates a
362f0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
36300 69 73 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  is structure to 
36310 70 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  pass.** to sqlit
36320 65 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e  e3_config() alon
36330 67 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  g with the [SQLI
36340 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
36350 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69   option..** Addi
36360 74 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73  tionally, an ins
36370 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
36380 72 75 63 74 75 72 65 20 63 61 6e 20 62 65 20 75  ructure can be u
36390 73 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74  sed as an.** out
363a0 70 75 74 20 76 61 72 69 61 62 6c 65 20 77 68 65  put variable whe
363b0 6e 20 71 75 65 72 79 69 6e 67 20 74 68 65 20 73  n querying the s
363c0 79 73 74 65 6d 20 66 6f 72 20 74 68 65 20 63 75  ystem for the cu
363d0 72 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69  rrent mutex.** i
363e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75  mplementation, u
363f0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
36400 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
36410 5d 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ] option..**.** 
36420 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20  ^The xMutexInit 
36430 6d 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62  method defined b
36440 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  y this structure
36450 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a   is invoked as.*
36460 2a 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d  * part of system
36470 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
36480 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
36490 6e 69 74 69 61 6c 69 7a 65 28 29 20 66 75 6e 63  nitialize() func
364a0 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 20 78 4d  tion..** ^The xM
364b0 75 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65  utexInit routine
364c0 20 69 73 20 63 61 6c 6c 65 20 62 79 20 53 51 4c   is calle by SQL
364d0 69 74 65 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  ite exactly once
364e0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66   for each.** eff
364f0 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b  ective call to [
36500 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
36510 7a 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ze()]..**.** ^Th
36520 65 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68  e xMutexEnd meth
36530 6f 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68  od defined by th
36540 69 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  is structure is 
36550 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61  invoked as.** pa
36560 72 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75  rt of system shu
36570 74 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71 6c  tdown by the sql
36580 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
36590 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a  function. The.**
365a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
365b0 6f 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69  of this method i
365c0 73 20 65 78 70 65 63 74 65 64 20 74 6f 20 72 65  s expected to re
365d0 6c 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 61  lease all outsta
365e0 6e 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63  nding.** resourc
365f0 65 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74  es obtained by t
36600 68 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73  he mutex methods
36610 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c   implementation,
36620 20 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74   especially.** t
36630 68 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62 79  hose obtained by
36640 20 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20   the xMutexInit 
36650 6d 65 74 68 6f 64 2e 20 20 5e 54 68 65 20 78 4d  method.  ^The xM
36660 75 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e 74  utexEnd().** int
36670 65 72 66 61 63 65 20 69 73 20 69 6e 76 6f 6b 65  erface is invoke
36680 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 66  d exactly once f
36690 6f 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20  or each call to 
366a0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
366b0 6e 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  n()]..**.** ^(Th
366c0 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 65  e remaining seve
366d0 6e 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65  n methods define
366e0 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74  d by this struct
366f0 75 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63  ure (xMutexAlloc
36700 2c 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 2c  ,.** xMutexFree,
36710 20 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 4d   xMutexEnter, xM
36720 75 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78 4c  utexTry, xMutexL
36730 65 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c 64  eave, xMutexHeld
36740 20 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f   and.** xMutexNo
36750 74 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74  theld) implement
36760 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69   the following i
36770 6e 74 65 72 66 61 63 65 73 20 28 72 65 73 70 65  nterfaces (respe
36780 63 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20  ctively):.**.** 
36790 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  <ul>.**   <li>  
367a0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
367b0 6c 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  lloc()] </li>.**
367c0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
367d0 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d 20  3_mutex_free()] 
367e0 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
367f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
36800 65 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  enter()] </li>.*
36810 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
36820 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d 20  e3_mutex_try()] 
36830 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
36840 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
36850 6c 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  leave()] </li>.*
36860 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
36870 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d  e3_mutex_held()]
36880 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
36890 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
368a0 5f 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69  _notheld()] </li
368b0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  >.** </ul>)^.**.
368c0 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  ** The only diff
368d0 65 72 65 6e 63 65 20 69 73 20 74 68 61 74 20 74  erence is that t
368e0 68 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65  he public sqlite
368f0 33 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20  3_XXX functions 
36900 65 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62  enumerated.** ab
36910 6f 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  ove silently ign
36920 6f 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69  ore any invocati
36930 6f 6e 73 20 74 68 61 74 20 70 61 73 73 20 61 20  ons that pass a 
36940 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73  NULL pointer ins
36950 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c  tead.** of a val
36960 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e  id mutex handle.
36970 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
36980 69 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68  ions of the meth
36990 6f 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62  ods defined.** b
369a0 79 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  y this structure
369b0 20 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65   are not require
369c0 64 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73  d to handle this
369d0 20 63 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c   case, the resul
369e0 74 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67  ts.** of passing
369f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
36a00 69 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c  instead of a val
36a10 69 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20  id mutex handle 
36a20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a  are undefined.**
36a30 20 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63   (i.e. it is acc
36a40 65 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69  eptable to provi
36a50 64 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  de an implementa
36a60 74 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75  tion that segfau
36a70 6c 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20  lts if.** it is 
36a80 70 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f  passed a NULL po
36a90 69 6e 74 65 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  inter)..**.** Th
36aa0 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d  e xMutexInit() m
36ab0 65 74 68 6f 64 20 6d 75 73 74 20 62 65 20 74 68  ethod must be th
36ac0 72 65 61 64 73 61 66 65 2e 20 20 5e 49 74 20 6d  readsafe.  ^It m
36ad0 75 73 74 20 62 65 20 68 61 72 6d 6c 65 73 73 20  ust be harmless 
36ae0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 78 4d 75  to.** invoke xMu
36af0 74 65 78 49 6e 69 74 28 29 20 6d 75 74 69 70 6c  texInit() mutipl
36b00 65 20 74 69 6d 65 73 20 77 69 74 68 69 6e 20 74  e times within t
36b10 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 20  he same process 
36b20 61 6e 64 20 77 69 74 68 6f 75 74 0a 2a 2a 20 69  and without.** i
36b30 6e 74 65 72 76 65 6e 69 6e 67 20 63 61 6c 6c 73  ntervening calls
36b40 20 74 6f 20 78 4d 75 74 65 78 45 6e 64 28 29 2e   to xMutexEnd().
36b50 20 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62    Second and sub
36b60 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
36b70 0a 2a 2a 20 78 4d 75 74 65 78 49 6e 69 74 28 29  .** xMutexInit()
36b80 20 6d 75 73 74 20 62 65 20 6e 6f 2d 6f 70 73 2e   must be no-ops.
36b90 0a 2a 2a 0a 2a 2a 20 5e 78 4d 75 74 65 78 49 6e  .**.** ^xMutexIn
36ba0 69 74 28 29 20 6d 75 73 74 20 6e 6f 74 20 75 73  it() must not us
36bb0 65 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20  e SQLite memory 
36bc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 5b 73 71 6c  allocation ([sql
36bd0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
36be0 2a 20 61 6e 64 20 69 74 73 20 61 73 73 6f 63 69  * and its associ
36bf0 61 74 65 73 29 2e 20 20 5e 53 69 6d 69 6c 61 72  ates).  ^Similar
36c00 6c 79 2c 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28  ly, xMutexAlloc(
36c10 29 20 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53  ) must not use S
36c20 51 4c 69 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  QLite memory.** 
36c30 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61  allocation for a
36c40 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20 20   static mutex.  
36c50 5e 48 6f 77 65 76 65 72 20 78 4d 75 74 65 78 41  ^However xMutexA
36c60 6c 6c 6f 63 28 29 20 6d 61 79 20 75 73 65 20 53  lloc() may use S
36c70 51 4c 69 74 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  QLite.** memory 
36c80 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61  allocation for a
36c90 20 66 61 73 74 20 6f 72 20 72 65 63 75 72 73 69   fast or recursi
36ca0 76 65 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20  ve mutex..**.** 
36cb0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76  ^SQLite will inv
36cc0 6f 6b 65 20 74 68 65 20 78 4d 75 74 65 78 45 6e  oke the xMutexEn
36cd0 64 28 29 20 6d 65 74 68 6f 64 20 77 68 65 6e 20  d() method when 
36ce0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
36cf0 6e 28 29 5d 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  n()] is.** calle
36d00 64 2c 20 62 75 74 20 6f 6e 6c 79 20 69 66 20 74  d, but only if t
36d10 68 65 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f  he prior call to
36d20 20 78 4d 75 74 65 78 49 6e 69 74 20 72 65 74 75   xMutexInit retu
36d30 72 6e 65 64 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  rned SQLITE_OK..
36d40 2a 2a 20 49 66 20 78 4d 75 74 65 78 49 6e 69 74  ** If xMutexInit
36d50 20 66 61 69 6c 73 20 69 6e 20 61 6e 79 20 77 61   fails in any wa
36d60 79 2c 20 69 74 20 69 73 20 65 78 70 65 63 74 65  y, it is expecte
36d70 64 20 74 6f 20 63 6c 65 61 6e 20 75 70 20 61 66  d to clean up af
36d80 74 65 72 20 69 74 73 65 6c 66 0a 2a 2a 20 70 72  ter itself.** pr
36d90 69 6f 72 20 74 6f 20 72 65 74 75 72 6e 69 6e 67  ior to returning
36da0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
36db0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  uct sqlite3_mute
36dc0 78 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  x_methods sqlite
36dd0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 3b  3_mutex_methods;
36de0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
36df0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 7b 0a  mutex_methods {.
36e00 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 49 6e    int (*xMutexIn
36e10 69 74 29 28 76 6f 69 64 29 3b 0a 20 20 69 6e 74  it)(void);.  int
36e20 20 28 2a 78 4d 75 74 65 78 45 6e 64 29 28 76 6f   (*xMutexEnd)(vo
36e30 69 64 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 6d  id);.  sqlite3_m
36e40 75 74 65 78 20 2a 28 2a 78 4d 75 74 65 78 41 6c  utex *(*xMutexAl
36e50 6c 6f 63 29 28 69 6e 74 29 3b 0a 20 20 76 6f 69  loc)(int);.  voi
36e60 64 20 28 2a 78 4d 75 74 65 78 46 72 65 65 29 28  d (*xMutexFree)(
36e70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
36e80 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65  ;.  void (*xMute
36e90 78 45 6e 74 65 72 29 28 73 71 6c 69 74 65 33 5f  xEnter)(sqlite3_
36ea0 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20  mutex *);.  int 
36eb0 28 2a 78 4d 75 74 65 78 54 72 79 29 28 73 71 6c  (*xMutexTry)(sql
36ec0 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20  ite3_mutex *);. 
36ed0 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78 4c 65   void (*xMutexLe
36ee0 61 76 65 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  ave)(sqlite3_mut
36ef0 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ex *);.  int (*x
36f00 4d 75 74 65 78 48 65 6c 64 29 28 73 71 6c 69 74  MutexHeld)(sqlit
36f10 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20 69  e3_mutex *);.  i
36f20 6e 74 20 28 2a 78 4d 75 74 65 78 4e 6f 74 68 65  nt (*xMutexNothe
36f30 6c 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ld)(sqlite3_mute
36f40 78 20 2a 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  x *);.};../*.** 
36f50 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
36f60 56 65 72 69 66 69 63 61 74 69 6f 6e 20 52 6f 75  Verification Rou
36f70 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tines.**.** The 
36f80 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65  sqlite3_mutex_he
36f90 6c 64 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ld() and sqlite3
36fa0 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29  _mutex_notheld()
36fb0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
36fc0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
36fd0 65 20 69 6e 73 69 64 65 20 61 73 73 65 72 74 28  e inside assert(
36fe0 29 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  ) statements.  ^
36ff0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 0a  The SQLite core.
37000 2a 2a 20 6e 65 76 65 72 20 75 73 65 73 20 74 68  ** never uses th
37010 65 73 65 20 72 6f 75 74 69 6e 65 73 20 65 78 63  ese routines exc
37020 65 70 74 20 69 6e 73 69 64 65 20 61 6e 20 61 73  ept inside an as
37030 73 65 72 74 28 29 20 61 6e 64 20 61 70 70 6c 69  sert() and appli
37040 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 61  cations.** are a
37050 64 76 69 73 65 64 20 74 6f 20 66 6f 6c 6c 6f 77  dvised to follow
37060 20 74 68 65 20 6c 65 61 64 20 6f 66 20 74 68 65   the lead of the
37070 20 63 6f 72 65 2e 20 20 5e 54 68 65 20 53 51 4c   core.  ^The SQL
37080 69 74 65 20 63 6f 72 65 20 6f 6e 6c 79 0a 2a 2a  ite core only.**
37090 20 70 72 6f 76 69 64 65 73 20 69 6d 70 6c 65 6d   provides implem
370a0 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 74 68  entations for th
370b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 68 65  ese routines whe
370c0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
370d0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 53 51 4c  .** with the SQL
370e0 49 54 45 5f 44 45 42 55 47 20 66 6c 61 67 2e 20  ITE_DEBUG flag. 
370f0 20 5e 45 78 74 65 72 6e 61 6c 20 6d 75 74 65 78   ^External mutex
37100 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
37110 0a 2a 2a 20 61 72 65 20 6f 6e 6c 79 20 72 65 71  .** are only req
37120 75 69 72 65 64 20 74 6f 20 70 72 6f 76 69 64 65  uired to provide
37130 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
37140 69 66 20 53 51 4c 49 54 45 5f 44 45 42 55 47 20  if SQLITE_DEBUG 
37150 69 73 0a 2a 2a 20 64 65 66 69 6e 65 64 20 61 6e  is.** defined an
37160 64 20 69 66 20 4e 44 45 42 55 47 20 69 73 20 6e  d if NDEBUG is n
37170 6f 74 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  ot defined..**.*
37180 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
37190 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  s should return 
371a0 74 72 75 65 20 69 66 20 74 68 65 20 6d 75 74 65  true if the mute
371b0 78 20 69 6e 20 74 68 65 69 72 20 61 72 67 75 6d  x in their argum
371c0 65 6e 74 0a 2a 2a 20 69 73 20 68 65 6c 64 20 6f  ent.** is held o
371d0 72 20 6e 6f 74 20 68 65 6c 64 2c 20 72 65 73 70  r not held, resp
371e0 65 63 74 69 76 65 6c 79 2c 20 62 79 20 74 68 65  ectively, by the
371f0 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 2e   calling thread.
37200 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c  .**.** ^The impl
37210 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 6f  ementation is no
37220 74 20 72 65 71 75 69 72 65 64 20 74 6f 20 70 72  t required to pr
37230 6f 76 69 64 65 64 20 76 65 72 73 69 6f 6e 73 20  ovided versions 
37240 6f 66 20 74 68 65 73 65 0a 2a 2a 20 72 6f 75 74  of these.** rout
37250 69 6e 65 73 20 74 68 61 74 20 61 63 74 75 61 6c  ines that actual
37260 6c 79 20 77 6f 72 6b 2e 20 49 66 20 74 68 65 20  ly work. If the 
37270 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64  implementation d
37280 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65 20  oes not provide 
37290 77 6f 72 6b 69 6e 67 0a 2a 2a 20 76 65 72 73 69  working.** versi
372a0 6f 6e 73 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ons of these rou
372b0 74 69 6e 65 73 2c 20 69 74 20 73 68 6f 75 6c 64  tines, it should
372c0 20 61 74 20 6c 65 61 73 74 20 70 72 6f 76 69 64   at least provid
372d0 65 20 73 74 75 62 73 20 74 68 61 74 20 61 6c 77  e stubs that alw
372e0 61 79 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 72  ays.** return tr
372f0 75 65 20 73 6f 20 74 68 61 74 20 6f 6e 65 20 64  ue so that one d
37300 6f 65 73 20 6e 6f 74 20 67 65 74 20 73 70 75 72  oes not get spur
37310 69 6f 75 73 20 61 73 73 65 72 74 69 6f 6e 20 66  ious assertion f
37320 61 69 6c 75 72 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ailures..**.** ^
37330 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  If the argument 
37340 74 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  to sqlite3_mutex
37350 5f 68 65 6c 64 28 29 20 69 73 20 61 20 4e 55 4c  _held() is a NUL
37360 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a  L pointer then.*
37370 2a 20 74 68 65 20 72 6f 75 74 69 6e 65 20 73 68  * the routine sh
37380 6f 75 6c 64 20 72 65 74 75 72 6e 20 31 2e 20 20  ould return 1.  
37390 20 54 68 69 73 20 73 65 65 6d 73 20 63 6f 75 6e   This seems coun
373a0 74 65 72 2d 69 6e 74 75 69 74 69 76 65 20 73 69  ter-intuitive si
373b0 6e 63 65 0a 2a 2a 20 63 6c 65 61 72 6c 79 20 74  nce.** clearly t
373c0 68 65 20 6d 75 74 65 78 20 63 61 6e 6e 6f 74 20  he mutex cannot 
373d0 62 65 20 68 65 6c 64 20 69 66 20 69 74 20 64 6f  be held if it do
373e0 65 73 20 6e 6f 74 20 65 78 69 73 74 2e 20 20 42  es not exist.  B
373f0 75 74 20 74 68 65 0a 2a 2a 20 74 68 65 20 72 65  ut the.** the re
37400 61 73 6f 6e 20 74 68 65 20 6d 75 74 65 78 20 64  ason the mutex d
37410 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 73  oes not exist is
37420 20 62 65 63 61 75 73 65 20 74 68 65 20 62 75 69   because the bui
37430 6c 64 20 69 73 20 6e 6f 74 0a 2a 2a 20 75 73 69  ld is not.** usi
37440 6e 67 20 6d 75 74 65 78 65 73 2e 20 20 41 6e 64  ng mutexes.  And
37450 20 77 65 20 64 6f 20 6e 6f 74 20 77 61 6e 74 20   we do not want 
37460 74 68 65 20 61 73 73 65 72 74 28 29 20 63 6f 6e  the assert() con
37470 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63  taining the.** c
37480 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  all to sqlite3_m
37490 75 74 65 78 5f 68 65 6c 64 28 29 20 74 6f 20 66  utex_held() to f
374a0 61 69 6c 2c 20 73 6f 20 61 20 6e 6f 6e 2d 7a 65  ail, so a non-ze
374b0 72 6f 20 72 65 74 75 72 6e 20 69 73 0a 2a 2a 20  ro return is.** 
374c0 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
374d0 74 68 69 6e 67 20 74 6f 20 64 6f 2e 20 20 5e 54  thing to do.  ^T
374e0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
374f0 5f 6e 6f 74 68 65 6c 64 28 29 0a 2a 2a 20 69 6e  _notheld().** in
37500 74 65 72 66 61 63 65 20 73 68 6f 75 6c 64 20 61  terface should a
37510 6c 73 6f 20 72 65 74 75 72 6e 20 31 20 77 68 65  lso return 1 whe
37520 6e 20 67 69 76 65 6e 20 61 20 4e 55 4c 4c 20 70  n given a NULL p
37530 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64  ointer..*/.#ifnd
37540 65 66 20 4e 44 45 42 55 47 0a 69 6e 74 20 73 71  ef NDEBUG.int sq
37550 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
37560 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29  (sqlite3_mutex*)
37570 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75  ;.int sqlite3_mu
37580 74 65 78 5f 6e 6f 74 68 65 6c 64 28 73 71 6c 69  tex_notheld(sqli
37590 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 23 65 6e  te3_mutex*);.#en
375a0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
375b0 52 45 46 3a 20 4d 75 74 65 78 20 54 79 70 65 73  REF: Mutex Types
375c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
375d0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
375e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 61 6b  )] interface tak
375f0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
37600 6d 65 6e 74 0a 2a 2a 20 77 68 69 63 68 20 69 73  ment.** which is
37610 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
37620 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 2e  teger constants.
37630 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 74 20 6f  .**.** The set o
37640 66 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  f static mutexes
37650 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d   may change from
37660 20 6f 6e 65 20 53 51 4c 69 74 65 20 72 65 6c 65   one SQLite rele
37670 61 73 65 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  ase to the.** ne
37680 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
37690 73 20 74 68 61 74 20 6f 76 65 72 72 69 64 65 20  s that override 
376a0 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 75 74  the built-in mut
376b0 65 78 20 6c 6f 67 69 63 20 6d 75 73 74 20 62 65  ex logic must be
376c0 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 74 6f 20  .** prepared to 
376d0 61 63 63 6f 6d 6d 6f 64 61 74 65 20 61 64 64 69  accommodate addi
376e0 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75  tional static mu
376f0 74 65 78 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  texes..*/.#defin
37700 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46  e SQLITE_MUTEX_F
37710 41 53 54 20 20 20 20 20 20 20 20 20 20 20 20 20  AST             
37720 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
37730 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
37740 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
37750 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
37760 54 41 54 49 43 5f 4d 41 53 54 45 52 20 20 20 20  TATIC_MASTER    
37770 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
37780 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
37790 4d 20 20 20 20 20 20 20 33 20 20 2f 2a 20 73 71  M       3  /* sq
377a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 2a  lite3_malloc() *
377b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
377c0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
377d0 4d 32 20 20 20 20 20 20 34 20 20 2f 2a 20 4e 4f  M2      4  /* NO
377e0 54 20 55 53 45 44 20 2a 2f 0a 23 64 65 66 69 6e  T USED */.#defin
377f0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
37800 54 41 54 49 43 5f 4f 50 45 4e 20 20 20 20 20 20  TATIC_OPEN      
37810 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 42 74 72  4  /* sqlite3Btr
37820 65 65 4f 70 65 6e 28 29 20 2a 2f 0a 23 64 65 66  eeOpen() */.#def
37830 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
37840 5f 53 54 41 54 49 43 5f 50 52 4e 47 20 20 20 20  _STATIC_PRNG    
37850 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
37860 72 61 6e 64 6f 6d 28 29 20 2a 2f 0a 23 64 65 66  random() */.#def
37870 69 6e 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  ine SQLITE_MUTEX
37880 5f 53 54 41 54 49 43 5f 4c 52 55 20 20 20 20 20  _STATIC_LRU     
37890 20 20 36 20 20 2f 2a 20 6c 72 75 20 70 61 67 65    6  /* lru page
378a0 20 6c 69 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65   list */.#define
378b0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
378c0 41 54 49 43 5f 4c 52 55 32 20 20 20 20 20 20 37  ATIC_LRU2      7
378d0 20 20 2f 2a 20 6c 72 75 20 70 61 67 65 20 6c 69    /* lru page li
378e0 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  st */../*.** CAP
378f0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 65 20  I3REF: Retrieve 
37900 74 68 65 20 6d 75 74 65 78 20 66 6f 72 20 61 20  the mutex for a 
37910 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37920 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ion.**.** ^This 
37930 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37940 73 20 61 20 70 6f 69 6e 74 65 72 20 74 68 65 20  s a pointer the 
37950 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
37960 6f 62 6a 65 63 74 20 74 68 61 74 20 0a 2a 2a 20  object that .** 
37970 73 65 72 69 61 6c 69 7a 65 73 20 61 63 63 65 73  serializes acces
37980 73 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61  s to the [databa
37990 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 67  se connection] g
379a0 69 76 65 6e 20 69 6e 20 74 68 65 20 61 72 67 75  iven in the argu
379b0 6d 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ment.** when the
379c0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
379d0 5d 20 69 73 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] is Serialized.
379e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 74 68 72  .** ^If the [thr
379f0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20  eading mode] is 
37a00 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 6f 72  Single-thread or
37a10 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 74 68   Multi-thread th
37a20 65 6e 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  en this.** routi
37a30 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
37a40 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71  L pointer..*/.sq
37a50 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 73 71 6c  lite3_mutex *sql
37a60 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 28 73 71  ite3_db_mutex(sq
37a70 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
37a80 43 41 50 49 33 52 45 46 3a 20 4c 6f 77 2d 4c 65  CAPI3REF: Low-Le
37a90 76 65 6c 20 43 6f 6e 74 72 6f 6c 20 4f 66 20 44  vel Control Of D
37aa0 61 74 61 62 61 73 65 20 46 69 6c 65 73 20 7b 48  atabase Files {H
37ab0 31 31 33 30 30 7d 20 3c 53 33 30 38 30 30 3e 0a  11300} <S30800>.
37ac0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
37ad0 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
37ae0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 6d 61  ()] interface ma
37af0 6b 65 73 20 61 20 64 69 72 65 63 74 20 63 61 6c  kes a direct cal
37b00 6c 20 74 6f 20 74 68 65 0a 2a 2a 20 78 46 69 6c  l to the.** xFil
37b10 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
37b20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
37b30 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
37b40 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  ect associated.*
37b50 2a 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  * with a particu
37b60 6c 61 72 20 64 61 74 61 62 61 73 65 20 69 64 65  lar database ide
37b70 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ntified by the s
37b80 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20  econd argument. 
37b90 5e 54 68 65 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  ^The.** name of 
37ba0 74 68 65 20 64 61 74 61 62 61 73 65 20 22 6d 61  the database "ma
37bb0 69 6e 22 20 66 6f 72 20 74 68 65 20 6d 61 69 6e  in" for the main
37bc0 20 64 61 74 61 62 61 73 65 20 6f 72 20 22 74 65   database or "te
37bd0 6d 70 22 20 66 6f 72 20 74 68 65 0a 2a 2a 20 54  mp" for the.** T
37be0 45 4d 50 20 64 61 74 61 62 61 73 65 2c 20 6f 72  EMP database, or
37bf0 20 74 68 65 20 6e 61 6d 65 20 74 68 61 74 20 61   the name that a
37c00 70 70 65 61 72 73 20 61 66 74 65 72 20 74 68 65  ppears after the
37c10 20 41 53 20 6b 65 79 77 6f 72 64 20 66 6f 72 0a   AS keyword for.
37c20 2a 2a 20 64 61 74 61 62 61 73 65 73 20 74 68 61  ** databases tha
37c30 74 20 61 72 65 20 61 64 64 65 64 20 75 73 69 6e  t are added usin
37c40 67 20 74 68 65 20 5b 41 54 54 41 43 48 5d 20 53  g the [ATTACH] S
37c50 51 4c 20 63 6f 6d 6d 61 6e 64 2e 0a 2a 2a 20 5e  QL command..** ^
37c60 41 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 63  A NULL pointer c
37c70 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  an be used in pl
37c80 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 20 74 6f  ace of "main" to
37c90 20 72 65 66 65 72 20 74 6f 20 74 68 65 0a 2a 2a   refer to the.**
37ca0 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
37cb0 69 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ile..** ^The thi
37cc0 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
37cd0 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
37ce0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 61 72 65 20   routine.** are 
37cf0 70 61 73 73 65 64 20 64 69 72 65 63 74 6c 79 20  passed directly 
37d00 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 73  through to the s
37d10 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
37d20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 0a 2a 2a  parameters of.**
37d30 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
37d40 6c 20 6d 65 74 68 6f 64 2e 20 20 5e 54 68 65 20  l method.  ^The 
37d50 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
37d60 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
37d70 0a 2a 2a 20 6d 65 74 68 6f 64 20 62 65 63 6f 6d  .** method becom
37d80 65 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  es the return va
37d90 6c 75 65 20 6f 66 20 74 68 69 73 20 72 6f 75 74  lue of this rout
37da0 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ine..**.** ^If t
37db0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
37dc0 74 65 72 20 28 7a 44 62 4e 61 6d 65 29 20 64 6f  ter (zDbName) do
37dd0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 74 68 65  es not match the
37de0 20 6e 61 6d 65 20 6f 66 20 61 6e 79 0a 2a 2a 20   name of any.** 
37df0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 66 69  open database fi
37e00 6c 65 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f  le, then SQLITE_
37e10 45 52 52 4f 52 20 69 73 20 72 65 74 75 72 6e 65  ERROR is returne
37e20 64 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 0a  d.  ^This error.
37e30 2a 2a 20 63 6f 64 65 20 69 73 20 6e 6f 74 20 72  ** code is not r
37e40 65 6d 65 6d 62 65 72 65 64 20 61 6e 64 20 77 69  emembered and wi
37e50 6c 6c 20 6e 6f 74 20 62 65 20 72 65 63 61 6c 6c  ll not be recall
37e60 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 65  ed by [sqlite3_e
37e70 72 72 63 6f 64 65 28 29 5d 0a 2a 2a 20 6f 72 20  rrcode()].** or 
37e80 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
37e90 29 5d 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  )].  The underly
37ea0 69 6e 67 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  ing xFileControl
37eb0 20 6d 65 74 68 6f 64 20 6d 69 67 68 74 0a 2a 2a   method might.**
37ec0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 53 51 4c   also return SQL
37ed0 49 54 45 5f 45 52 52 4f 52 2e 20 20 54 68 65 72  ITE_ERROR.  Ther
37ee0 65 20 69 73 20 6e 6f 20 77 61 79 20 74 6f 20 64  e is no way to d
37ef0 69 73 74 69 6e 67 75 69 73 68 20 62 65 74 77 65  istinguish betwe
37f00 65 6e 0a 2a 2a 20 61 6e 20 69 6e 63 6f 72 72 65  en.** an incorre
37f10 63 74 20 7a 44 62 4e 61 6d 65 20 61 6e 64 20 61  ct zDbName and a
37f20 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 72  n SQLITE_ERROR r
37f30 65 74 75 72 6e 20 66 72 6f 6d 20 74 68 65 20 75  eturn from the u
37f40 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 78 46 69  nderlying.** xFi
37f50 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
37f60 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
37f70 3a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  : [SQLITE_FCNTL_
37f80 4c 4f 43 4b 53 54 41 54 45 5d 0a 2a 2f 0a 69 6e  LOCKSTATE].*/.in
37f90 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  t sqlite3_file_c
37fa0 6f 6e 74 72 6f 6c 28 73 71 6c 69 74 65 33 2a 2c  ontrol(sqlite3*,
37fb0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62   const char *zDb
37fc0 4e 61 6d 65 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  Name, int op, vo
37fd0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
37fe0 49 33 52 45 46 3a 20 54 65 73 74 69 6e 67 20 49  I3REF: Testing I
37ff0 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 5e  nterface.**.** ^
38000 54 68 65 20 73 71 6c 69 74 65 33 5f 74 65 73 74  The sqlite3_test
38010 5f 63 6f 6e 74 72 6f 6c 28 29 20 69 6e 74 65 72  _control() inter
38020 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
38030 72 65 61 64 20 6f 75 74 20 69 6e 74 65 72 6e 61  read out interna
38040 6c 0a 2a 2a 20 73 74 61 74 65 20 6f 66 20 53 51  l.** state of SQ
38050 4c 69 74 65 20 61 6e 64 20 74 6f 20 69 6e 6a 65  Lite and to inje
38060 63 74 20 66 61 75 6c 74 73 20 69 6e 74 6f 20 53  ct faults into S
38070 51 4c 69 74 65 20 66 6f 72 20 74 65 73 74 69 6e  QLite for testin
38080 67 0a 2a 2a 20 70 75 72 70 6f 73 65 73 2e 20 20  g.** purposes.  
38090 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
380a0 65 74 65 72 20 69 73 20 61 6e 20 6f 70 65 72 61  eter is an opera
380b0 74 69 6f 6e 20 63 6f 64 65 20 74 68 61 74 20 64  tion code that d
380c0 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 74 68 65  etermines.** the
380d0 20 6e 75 6d 62 65 72 2c 20 6d 65 61 6e 69 6e 67   number, meaning
380e0 2c 20 61 6e 64 20 6f 70 65 72 61 74 69 6f 6e 20  , and operation 
380f0 6f 66 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  of all subsequen
38100 74 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2a  t parameters..**
38110 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
38120 63 65 20 69 73 20 6e 6f 74 20 66 6f 72 20 75 73  ce is not for us
38130 65 20 62 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  e by application
38140 73 2e 20 20 49 74 20 65 78 69 73 74 73 20 73 6f  s.  It exists so
38150 6c 65 6c 79 0a 2a 2a 20 66 6f 72 20 76 65 72 69  lely.** for veri
38160 66 79 69 6e 67 20 74 68 65 20 63 6f 72 72 65 63  fying the correc
38170 74 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  t operation of t
38180 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
38190 79 2e 20 20 44 65 70 65 6e 64 69 6e 67 0a 2a 2a  y.  Depending.**
381a0 20 6f 6e 20 68 6f 77 20 74 68 65 20 53 51 4c 69   on how the SQLi
381b0 74 65 20 6c 69 62 72 61 72 79 20 69 73 20 63 6f  te library is co
381c0 6d 70 69 6c 65 64 2c 20 74 68 69 73 20 69 6e 74  mpiled, this int
381d0 65 72 66 61 63 65 20 6d 69 67 68 74 20 6e 6f 74  erface might not
381e0 20 65 78 69 73 74 2e 0a 2a 2a 0a 2a 2a 20 54 68   exist..**.** Th
381f0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
38200 20 6f 70 65 72 61 74 69 6f 6e 20 63 6f 64 65 73   operation codes
38210 2c 20 74 68 65 69 72 20 6d 65 61 6e 69 6e 67 73  , their meanings
38220 2c 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  , the parameters
38230 0a 2a 2a 20 74 68 65 79 20 74 61 6b 65 2c 20 61  .** they take, a
38240 6e 64 20 77 68 61 74 20 74 68 65 79 20 64 6f 20  nd what they do 
38250 61 72 65 20 61 6c 6c 20 73 75 62 6a 65 63 74 20  are all subject 
38260 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
38270 74 20 6e 6f 74 69 63 65 2e 0a 2a 2a 20 55 6e 6c  t notice..** Unl
38280 69 6b 65 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  ike most of the 
38290 53 51 4c 69 74 65 20 41 50 49 2c 20 74 68 69 73  SQLite API, this
382a0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74   function is not
382b0 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 0a 2a   guaranteed to.*
382c0 2a 20 6f 70 65 72 61 74 65 20 63 6f 6e 73 69 73  * operate consis
382d0 74 65 6e 74 6c 79 20 66 72 6f 6d 20 6f 6e 65 20  tently from one 
382e0 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
382f0 65 78 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ext..*/.int sqli
38300 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f 6c  te3_test_control
38310 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a  (int op, ...);..
38320 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38330 54 65 73 74 69 6e 67 20 49 6e 74 65 72 66 61 63  Testing Interfac
38340 65 20 4f 70 65 72 61 74 69 6f 6e 20 43 6f 64 65  e Operation Code
38350 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
38360 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
38370 76 61 6c 69 64 20 6f 70 65 72 61 74 69 6f 6e 20  valid operation 
38380 63 6f 64 65 20 70 61 72 61 6d 65 74 65 72 73 20  code parameters 
38390 75 73 65 64 0a 2a 2a 20 61 73 20 74 68 65 20 66  used.** as the f
383a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
383b0 20 5b 73 71 6c 69 74 65 33 5f 74 65 73 74 5f 63   [sqlite3_test_c
383c0 6f 6e 74 72 6f 6c 28 29 5d 2e 0a 2a 2a 0a 2a 2a  ontrol()]..**.**
383d0 20 54 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   These parameter
383e0 73 20 61 6e 64 20 74 68 65 69 72 20 6d 65 61 6e  s and their mean
383f0 69 6e 67 73 20 61 72 65 20 73 75 62 6a 65 63 74  ings are subject
38400 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 77 69   to change.** wi
38410 74 68 6f 75 74 20 6e 6f 74 69 63 65 2e 20 20 54  thout notice.  T
38420 68 65 73 65 20 76 61 6c 75 65 73 20 61 72 65 20  hese values are 
38430 66 6f 72 20 74 65 73 74 69 6e 67 20 70 75 72 70  for testing purp
38440 6f 73 65 73 20 6f 6e 6c 79 2e 0a 2a 2a 20 41 70  oses only..** Ap
38450 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
38460 64 20 6e 6f 74 20 75 73 65 20 61 6e 79 20 6f 66  d not use any of
38470 20 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72   these parameter
38480 73 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s or the.** [sql
38490 69 74 65 33 5f 74 65 73 74 5f 63 6f 6e 74 72 6f  ite3_test_contro
384a0 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  l()] interface..
384b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
384c0 45 5f 54 45 53 54 43 54 52 4c 5f 50 52 4e 47 5f  E_TESTCTRL_PRNG_
384d0 53 41 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SAVE            
384e0 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
384f0 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 52  LITE_TESTCTRL_PR
38500 4e 47 5f 52 45 53 54 4f 52 45 20 20 20 20 20 20  NG_RESTORE      
38510 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
38520 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c   SQLITE_TESTCTRL
38530 5f 50 52 4e 47 5f 52 45 53 45 54 20 20 20 20 20  _PRNG_RESET     
38540 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
38550 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43  ine SQLITE_TESTC
38560 54 52 4c 5f 42 49 54 56 45 43 5f 54 45 53 54 20  TRL_BITVEC_TEST 
38570 20 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23               8.#
38580 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
38590 53 54 43 54 52 4c 5f 46 41 55 4c 54 5f 49 4e 53  STCTRL_FAULT_INS
385a0 54 41 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  TALL            
385b0 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
385c0 5f 54 45 53 54 43 54 52 4c 5f 42 45 4e 49 47 4e  _TESTCTRL_BENIGN
385d0 5f 4d 41 4c 4c 4f 43 5f 48 4f 4f 4b 53 20 20 20  _MALLOC_HOOKS   
385e0 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
385f0 49 54 45 5f 54 45 53 54 43 54 52 4c 5f 50 45 4e  ITE_TESTCTRL_PEN
38600 44 49 4e 47 5f 42 59 54 45 20 20 20 20 20 20 20  DING_BYTE       
38610 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
38620 53 51 4c 49 54 45 5f 54 45 53 54 43 54 52 4c 5f  SQLITE_TESTCTRL_
38630 41 53 53 45 52 54 20 20 20 20 20 20 20 20 20 20  ASSERT          
38640 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
38650 6e 65 20 53 51 4c 49 54 45 5f 54 45 53 54 43 54  ne SQLITE_TESTCT
38660 52 4c 5f 41 4c 57 41 59 53 20 20 20 20 20 20 20  RL_ALWAYS       
38670 20 20 20 20 20 20 20 20 20 20 20 31 33 0a 23 64             13.#d
38680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 53  efine SQLITE_TES
38690 54 43 54 52 4c 5f 52 45 53 45 52 56 45 20 20 20  TCTRL_RESERVE   
386a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
386b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
386c0 3a 20 53 51 4c 69 74 65 20 52 75 6e 74 69 6d 65  : SQLite Runtime
386d0 20 53 74 61 74 75 73 0a 2a 2a 20 45 58 50 45 52   Status.** EXPER
386e0 49 4d 45 4e 54 41 4c 0a 2a 2a 0a 2a 2a 20 5e 54  IMENTAL.**.** ^T
386f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
38700 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
38710 65 20 72 75 6e 74 69 6d 65 20 73 74 61 74 75 73  e runtime status
38720 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
38730 61 62 6f 75 74 20 74 68 65 20 70 72 65 66 6f 72  about the prefor
38740 6d 61 6e 63 65 20 6f 66 20 53 51 4c 69 74 65 2c  mance of SQLite,
38750 20 61 6e 64 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   and optionally 
38760 74 6f 20 72 65 73 65 74 20 76 61 72 69 6f 75 73  to reset various
38770 0a 2a 2a 20 68 69 67 68 77 61 74 65 72 20 6d 61  .** highwater ma
38780 72 6b 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74  rks.  ^The first
38790 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
387a0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 66 6f 72  integer code for
387b0 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 66 69 63  .** the specific
387c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 6d 65   parameter to me
387d0 61 73 75 72 65 2e 20 20 5e 52 65 63 6f 67 6e 69  asure.  ^Recogni
387e0 7a 65 64 20 69 6e 74 65 67 65 72 20 63 6f 64 65  zed integer code
387f0 73 0a 2a 2a 20 61 72 65 20 6f 66 20 74 68 65 20  s.** are of the 
38800 66 6f 72 6d 20 5b 53 51 4c 49 54 45 5f 53 54 41  form [SQLITE_STA
38810 54 55 53 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 20  TUS_MEMORY_USED 
38820 7c 20 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f  | SQLITE_STATUS_
38830 2e 2e 2e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 63 75  ...]..** ^The cu
38840 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 74  rrent value of t
38850 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
38860 72 65 74 75 72 6e 65 64 20 69 6e 74 6f 20 2a 70  returned into *p
38870 43 75 72 72 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  Current..** ^The
38880 20 68 69 67 68 65 73 74 20 72 65 63 6f