/ Hex Artifact Content
Login

Artifact 373dedd8489ecd9dfb33d6d4378ee9f34a3c2386:


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 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
10b0: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
10c0: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
10d0: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
10e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
10f0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
1100: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
1110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
1120: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
1130: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
1140: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
1150: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
1160: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
1170: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
1180: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
1190: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
11a0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
11b0: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
11c0: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
11d0: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
11e0: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
11f0: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
1200: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
1210: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
1220: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
1230: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
1240: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
1250: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1260: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
1270: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
1280: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
1290: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
12a0: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
12b0: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
12c0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
12d0: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
12e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
12f0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1300: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
1310: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
1320: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
1330: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
1340: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1350: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
1360: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
1370: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1380: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1390: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
13a0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
13b0: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
13c0: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
13d0: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
13e0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
13f0: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
1400: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
1410: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
1420: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1430: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
1440: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
1450: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1460: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
1470: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
1480: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
1490: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
14a0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
14b0: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
14c0: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
14d0: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
14e0: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
14f0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1500: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
1510: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1520: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
1530: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
1540: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
1550: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
1560: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
1570: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
1580: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
1590: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
15a0: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
15b0: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
15c0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
15d0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
15e0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
15f0: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
1600: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
1610: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
1620: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54 45  ..*/.SQLITE_EXTE
1630: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
1640: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
1650: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1660: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
1670: 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68 61  void);.const cha
1680: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
1690: 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  eid(void);.int s
16a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
16b0: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
16c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16d0: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
16e0: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
16f0: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1700: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1710: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1720: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
1730: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
1740: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
1750: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
1760: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
1770: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1780: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1790: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
17a0: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
17b0: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
17c0: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
17d0: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
17e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
17f0: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1800: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1810: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
1820: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 6e 74  ction allows int
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
19f0: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a00: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a10: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1a20: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1a30: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1a40: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1a50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1a60: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1a70: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a80: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1a90: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1aa0: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1ab0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1ac0: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1ad0: 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  GS.int sqlite3_c
1ae0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1af0: 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f  d(const char *zO
1b00: 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20 63  ptName);.const c
1b10: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d  har *sqlite3_com
1b20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
1b30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
1b40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1b50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
1b60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
1b70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
1b80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
1b90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
1ba0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
1bb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
1bc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
1bd0: 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f 64  led mutexing cod
1be0: 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f  e omitted due to
1bf0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
1c00: 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70  THREADSAFE] comp
1c10: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
1c20: 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a  being set to 0..
1c30: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e  **.** SQLite can
1c40: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   be compiled wit
1c50: 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74  h or without mut
1c60: 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74  exes.  When.** t
1c70: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1c80: 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63  DSAFE] C preproc
1c90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31  essor macro is 1
1ca0: 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a   or 2, mutexes.*
1cb0: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e  * are enabled an
1cc0: 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65  d SQLite is thre
1cd0: 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68  adsafe.  When th
1ce0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cf0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69  EADSAFE] macro i
1d00: 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74  s 0, .** the mut
1d10: 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64  exes are omitted
1d20: 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d  .  Without the m
1d30: 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f  utexes, it is no
1d40: 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65  t safe.** to use
1d50: 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65   SQLite concurre
1d60: 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74  ntly from more t
1d70: 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a  han one thread..
1d80: 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d  **.** Enabling m
1d90: 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20  utexes incurs a 
1da0: 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f  measurable perfo
1db0: 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a  rmance penalty..
1dc0: 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69  ** So if speed i
1dd0: 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f  s of utmost impo
1de0: 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73  rtance, it makes
1df0: 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c   sense to disabl
1e00: 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73  e.** the mutexes
1e10: 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d  .  But for maxim
1e20: 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78  um safety, mutex
1e30: 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61  es should be ena
1e40: 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  bled..** ^The de
1e50: 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
1e60: 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f  s for mutexes to
1e70: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   be enabled..**.
1e80: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1e90: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79  e can be used by
1ea0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1eb0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
1ec0: 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  t the.** version
1ed0: 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20   of SQLite that 
1ee0: 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67  it is linking ag
1ef0: 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c  ainst was compil
1f00: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64  ed with.** the d
1f10: 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f  esired setting o
1f20: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
1f30: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e  READSAFE] macro.
1f40: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f50: 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72  rface only repor
1f60: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c  ts on the compil
1f70: 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74  e-time mutex set
1f80: 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ting.** of the [
1f90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fa0: 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c  E] flag.  If SQL
1fb0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  with.** SQLITE_T
1fd0: 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d  HREADSAFE=1 or =
1fe0: 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61  2 then mutexes a
1ff0: 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65  re enabled by de
2000: 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e  fault but.** can
2010: 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72   be fully or par
2020: 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20  tially disabled 
2030: 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  using a call to 
2040: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
2050: 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76  )].** with the v
2060: 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  erbs [SQLITE_CON
2070: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2080: 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ], [SQLITE_CONFI
2090: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a  G_MULTITHREAD],.
20a0: 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  ** or [SQLITE_CO
20b0: 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e 28  NFIG_MUTEX].  ^(
20c0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
20d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   of the.** sqlit
20e0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
20f0: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f  function shows o
2100: 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d  nly the compile-
2110: 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 0a  time setting of.
2120: 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 79  ** thread safety
2130: 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69  , not any run-ti
2140: 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  me changes to th
2150: 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 20  at setting made 
2160: 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  by.** sqlite3_co
2170: 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 72  nfig(). In other
2180: 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 75   words, the retu
2190: 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
21a0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
21b0: 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67  ().** is unchang
21c0: 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 73  ed by calls to s
21d0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
21e0: 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65  )^.**.** See the
21f0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
2200: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
2210: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
2220: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69  nformation..*/.i
2230: 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  nt sqlite3_threa
2240: 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a  dsafe(void);../*
2250: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
2260: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2270: 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57  n Handle.** KEYW
2280: 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20  ORDS: {database 
2290: 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74  connection} {dat
22a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22b0: 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70  s}.**.** Each op
22c0: 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  en SQLite databa
22d0: 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  se is represente
22e0: 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74  d by a pointer t
22f0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
2300: 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73  .** the opaque s
2310: 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22  tructure named "
2320: 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73  sqlite3".  It is
2330: 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b   useful to think
2340: 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a   of an sqlite3.*
2350: 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20  * pointer as an 
2360: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71  object.  The [sq
2370: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2390: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
23a0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
23b0: 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73  terfaces are its
23c0: 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61   constructors, a
23d0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
23e0: 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64  e()].** is its d
23f0: 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72  estructor.  Ther
2400: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
2410: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2420: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2430: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2440: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2450: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2460: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2470: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2480: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2490: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
24a0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
24b0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
24c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
24d0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
24e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
24f0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
2500: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2510: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2520: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2530: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2540: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2550: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2560: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2570: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2580: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2590: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
25a0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
25b0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
25c0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
25d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
25e0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
25f0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
2600: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
2610: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2620: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2630: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2640: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2650: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2660: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2670: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2680: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2690: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
26a0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
26b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
26c0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
26d0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
26e0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
26f0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
2700: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
2710: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2720: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2730: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2740: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2750: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2760: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2770: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2780: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2790: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
27a0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
27b0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
27c0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
27d0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
27e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
27f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2800: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2810: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2820: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2840: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2850: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2860: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2870: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2880: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2890: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
28a0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
28b0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
28c0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
28d0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
28e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2900: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2910: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2920: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2930: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2940: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2950: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2960: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2970: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2980: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2990: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
29a0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
29b0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
29c0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
29d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
29e0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
29f0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2a00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a10: 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69  e3_close() routi
2a20: 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75  ne is the destru
2a30: 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71  ctor for the [sq
2a40: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2a50: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2a60: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75  te3_close() retu
2a70: 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
2a80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2a90: 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65  ject is.** succe
2aa0: 73 73 66 75 6c 6c 6c 79 20 64 65 73 74 72 6f 79  ssfullly destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5630: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
5640: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
5650: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5660: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5670: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5680: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5690: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
56a0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
56b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
56c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
56d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
56e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
56f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5700: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5710: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5720: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5730: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5740: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5750: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5760: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5790: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
57a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
57c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
57d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
57e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
57f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5800: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5810: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5820: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5830: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5840: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5850: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5860: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5870: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5880: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5890: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
58a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
58b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
58c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
58d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
58e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
58f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5900: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5910: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5930: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5940: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5950: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5970: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5980: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5990: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
59a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
59b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
59c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
59d0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
59f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
5a00: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a20: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
5a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a40: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
5a70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5a90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ab0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
5ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5ae0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b00: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
5b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5b50: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b70: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
5b80: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ba0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5bc0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5be0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
5bf0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c10: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
5c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c30: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
5c50: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
5c60: 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a  0x00000800../*.*
5c70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5c80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5c90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5ca0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5cb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5cc0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5cd0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ce0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5cf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5d30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5d50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5d70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5d90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5da0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5dc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5de0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5e20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5e30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5e40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5e70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5e80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5e90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ea0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5eb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ee0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5ef0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5f00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5f10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5f20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5f30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5f40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5f50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5f60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5f70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5f80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5fa0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5fb0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5fc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5fd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5fe0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5ff0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6000: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6010: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6020: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6030: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
6040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6050: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6060: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6070: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6080: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6090: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
60a0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
60b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
60c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
60d0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
60e0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
60f0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6100: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6110: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6120: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
6130: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6140: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6150: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6160: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6180: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6190: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
61a0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
61b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
61c0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
61d0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
61e0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
61f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6200: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6210: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6220: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6230: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6240: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6250: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6260: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6270: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6280: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6290: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
62a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
62b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
62c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
62d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
62e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
62f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6300: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6310: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6320: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6330: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6340: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6360: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6370: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6380: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6390: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
63a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
63b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
63c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
63e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
63f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6400: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6410: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6420: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6430: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6440: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6450: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6480: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6490: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
64a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
64b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
64c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
64d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
64e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
64f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6500: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6510: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6520: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6530: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6540: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6550: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6560: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6570: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6580: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6590: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
65a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
65b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
65c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
65d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
65e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
65f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6600: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6610: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6620: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6630: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6640: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6650: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6660: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6670: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6680: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6690: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
66a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
66b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
66c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
66d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
66e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
66f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6700: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6710: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6720: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6730: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6740: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6750: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6770: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6780: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6790: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
67a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
67c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
67e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
67f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6800: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6810: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6820: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6830: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6840: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6850: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6860: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6870: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6880: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6890: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
68a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
68b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
68c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
68d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
68e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
68f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6900: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6910: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6920: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6930: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6940: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6950: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6960: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6970: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6980: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6990: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
69a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
69b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
69c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
69d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
69e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
69f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6a00: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6a10: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6a20: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6a30: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6a40: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6a50: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6a60: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6a70: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6a80: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6a90: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
6aa0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
6ab0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
6ac0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
6ad0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
6ae0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
6af0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6b00: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6b10: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6b20: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6b30: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6b40: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6b50: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6b60: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6b70: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6b80: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6b90: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6ba0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6bb0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
6bc0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
6bd0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
6be0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
6bf0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6c00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6c10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6c20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6c30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6c40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6c50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6c60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6c70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6c80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6c90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6ca0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6cb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6cc0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6cd0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ce0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6cf0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6d00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6d10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6d20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6d30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6d40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6d50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6d60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6d70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6d80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6d90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6da0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6db0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6dc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6dd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6de0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6df0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6e00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6e10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6e20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6e30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6e40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6e60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6e80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ea0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6eb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6ec0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6ed0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ee0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6ef0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6f00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6f10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6f20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6f30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6f40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6f50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6f60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6f70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6f90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6fa0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6fb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6fc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6fd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6fe0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6ff0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
7000: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
7010: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
7020: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
7030: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
7040: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
7050: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
7060: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
7070: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7080: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7090: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
70a0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
70b0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
70c0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
70d0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
70e0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
70f0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
7100: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
7110: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
7120: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
7130: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7140: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
7150: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
7160: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
7170: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
7180: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
7190: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
71a0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
71b0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
71c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
71d0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
71e0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
71f0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7200: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7210: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7220: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7230: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7240: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7250: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7260: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7270: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7280: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7290: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
72a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
72b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
72c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
72d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
72e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
72f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7300: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7310: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7320: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7330: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7340: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7350: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7360: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7370: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7380: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7390: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
73a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
73b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
73c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
73d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
73e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
73f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7400: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7410: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7420: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7430: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7440: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7450: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7460: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7470: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7480: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7490: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
74a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
74b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
74c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
74d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
74e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
74f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7500: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7510: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7520: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7530: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7540: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7550: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7560: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7580: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7590: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
75a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
75b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
75c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
75d0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
75e0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
75f0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
7600: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
7610: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
7620: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
7630: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
7640: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
7650: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7660: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
7670: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7680: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
7690: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
76a0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
76b0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
76c0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
76d0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
76e0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
76f0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
7700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7710: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
7720: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
7730: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
7740: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
7750: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
7760: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7770: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
7780: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7790: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
77a0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
77b0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
77c0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
77d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
77e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
77f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
7800: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
7810: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
7820: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
7830: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
7840: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
7850: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
7860: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
7870: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7880: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7890: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
78a0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
78b0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
78c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
78d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
78e0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
78f0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
7900: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
7910: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
7920: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
7930: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
7940: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
7950: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
7960: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
7970: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
7980: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ned..**.** The [
7990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
79a0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
79b0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
79c0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
79d0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
79e0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
79f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
7a00: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
7a10: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
7a20: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
7a30: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
7a40: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
7a50: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
7a60: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
7a70: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
7a80: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
7a90: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
7aa0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
7ab0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
7ac0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
7ad0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
7ae0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
7af0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
7b00: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
7b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7b20: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7b30: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
7b40: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
7b50: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
7b60: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
7b70: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
7b80: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  LE      3.#defin
7b90: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
7ba0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
7bb0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
7bc0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
7bd0: 20 20 20 20 20 20 20 20 35 0a 0a 2f 2a 0a 2a 2a          5../*.**
7be0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
7bf0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
7c00: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
7c10: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
7c20: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
7c30: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
7c40: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
7c50: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
7c60: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
7c70: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
7c80: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
7c90: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
7ca0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
7cb0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
7cc0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
7cd0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
7ce0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
7cf0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
7d00: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
7d10: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
7d20: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
7d30: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
7d40: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
7d50: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
7d60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7d70: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
7d80: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
7d90: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
7da0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
7db0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
7dc0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
7dd0: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
7de0: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
7df0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
7e00: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
7e10: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
7e20: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
7e30: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
7e40: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
7e50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65  .**.** The value
7e60: 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e   of the iVersion
7e70: 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61   field is initia
7e80: 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65  lly 1 but may be
7e90: 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75   larger in.** fu
7ea0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
7eb0: 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69   SQLite.  Additi
7ec0: 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20  onal fields may 
7ed0: 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74  be appended to t
7ee0: 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68  his.** object wh
7ef0: 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  en the iVersion 
7f00: 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73  value is increas
7f10: 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74  ed.  Note that t
7f20: 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  he structure.** 
7f30: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
7f40: 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65  fs object change
7f50: 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63  s in the transac
7f60: 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  tion between.** 
7f70: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
7f80: 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61  .5.9 and 3.6.0 a
7f90: 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73  nd yet the iVers
7fa0: 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f  ion field was no
7fb0: 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a  t.** modified..*
7fc0: 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c  *.** The szOsFil
7fd0: 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73  e field is the s
7fe0: 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c  ize of the subcl
7ff0: 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66  assed [sqlite3_f
8000: 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ile].** structur
8010: 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56  e used by this V
8020: 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20  FS.  mxPathname 
8030: 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c  is the maximum l
8040: 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61  ength of.** a pa
8050: 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56  thname in this V
8060: 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74  FS..**.** Regist
8070: 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73  ered sqlite3_vfs
8080: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70   objects are kep
8090: 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69  t on a linked li
80a0: 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20  st formed by.** 
80b0: 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65  the pNext pointe
80c0: 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  r.  The [sqlite3
80d0: 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d  _vfs_register()]
80e0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
80f0: 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28  _vfs_unregister(
8100: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  )] interfaces ma
8110: 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a  nage this list.*
8120: 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61  * in a thread-sa
8130: 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71  fe way.  The [sq
8140: 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29  lite3_vfs_find()
8150: 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73  ] interface.** s
8160: 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74  earches the list
8170: 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61  .  Neither the a
8180: 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
8190: 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69  nor the VFS.** i
81a0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68  mplementation sh
81b0: 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65  ould use the pNe
81c0: 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  xt pointer..**.*
81d0: 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c  * The pNext fiel
81e0: 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69  d is the only fi
81f0: 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74  eld in the sqlit
8200: 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74  e3_vfs.** struct
8210: 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ure that SQLite 
8220: 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79  will ever modify
8230: 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f  .  SQLite will o
8240: 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72  nly access.** or
8250: 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65   modify this fie
8260: 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67  ld while holding
8270: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74   a particular st
8280: 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54  atic mutex..** T
8290: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
82a0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69  hould never modi
82b0: 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68  fy anything with
82c0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
82d0: 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63  fs.** object onc
82e0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73  e the object has
82f0: 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64   been registered
8300: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d  ..**.** The zNam
8310: 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68  e field holds th
8320: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46  e name of the VF
8330: 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e  S module.  The n
8340: 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75  ame must.** be u
8350: 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c  nique across all
8360: 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a   VFS modules..**
8370: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
8380: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
8390: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
83a0: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
83b0: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
83c0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
83d0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
83e0: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
83f0: 6e 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20  name().  SQLite 
8400: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
8410: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
8420: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
8430: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
8440: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
8450: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
8460: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
8470: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
8480: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
8490: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
84a0: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
84b0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
84c0: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
84d0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
84e0: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
84f0: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
8500: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
8510: 61 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65  arameter is xOpe
8520: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
8530: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
8540: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
8550: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
8560: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
8570: 65 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65  e.  Whenever the
8580: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
8590: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
85a0: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
85b0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
85c0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
85d0: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
85e0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
85f0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
8600: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
8610: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
8620: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
8630: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
8640: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
8650: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
8660: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
8670: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
8680: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
8690: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
86a0: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
86b0: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
86c0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
86d0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
86e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
86f0: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
8700: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
8710: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
8720: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
8730: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
8740: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
8750: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
8760: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
8770: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
8780: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
8790: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
87a0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
87b0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
87c0: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
87d0: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
87e0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
87f0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
8800: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
8810: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
8820: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8830: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
8840: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
8850: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
8860: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8870: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
8880: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
8890: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
88a0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
88b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
88c0: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
88d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
88e0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
88f0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
8900: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
8910: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
8920: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
8930: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
8940: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
8950: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
8960: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
8970: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
8980: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
8990: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
89a0: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
89b0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
89c0: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
89d0: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
89e0: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
89f0: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
8a00: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
8a10: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
8a20: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
8a30: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
8a40: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
8a50: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
8a60: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
8a70: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
8a80: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
8a90: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
8aa0: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
8ab0: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
8ac0: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
8ad0: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
8ae0: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
8af0: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
8b00: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
8b10: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
8b20: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
8b30: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
8b40: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
8b50: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
8b60: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
8b70: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
8b80: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
8b90: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
8ba0: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
8bb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
8bc0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8bd0: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
8be0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
8bf0: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
8c00: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
8c10: 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
8c20: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
8c30: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
8c40: 65 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74  et for TEMP  dat
8c50: 61 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73  abases, journals
8c60: 20 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72   and for subjour
8c70: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nals..**.** The 
8c80: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
8c90: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
8ca0: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
8cb0: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
8cc0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
8cd0: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
8ce0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
8cf0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
8d00: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
8d10: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
8d20: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
8d30: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
8d40: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
8d50: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
8d60: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
8d70: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
8d80: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
8d90: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
8da0: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
8db0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
8dc0: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
8dd0: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
8de0: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
8df0: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
8e00: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
8e10: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
8e20: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
8e30: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
8e40: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
8e50: 73 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73  s..**.** At leas
8e60: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
8e70: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
8e80: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
8e90: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
8ea0: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
8eb0: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
8ec0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
8ed0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
8ee0: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
8ef0: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
8f00: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
8f10: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
8f20: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
8f30: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
8f40: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
8f50: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
8f60: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
8f70: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
8f80: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
8f90: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
8fa0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
8fb0: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
8fc0: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
8fd0: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
8fe0: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
8ff0: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
9000: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
9010: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
9020: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
9030: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
9040: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
9050: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
9060: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
9070: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
9080: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  ll..**.** The fl
9090: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
90a0: 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
90b0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
90c0: 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
90d0: 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
90e0: 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
90f0: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
9100: 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
9110: 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
9120: 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
9130: 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
9140: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
9150: 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
9160: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
9170: 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
9180: 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
9190: 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
91a0: 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
91b0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77   SQLite will alw
91c0: 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20  ays allocate at 
91d0: 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65  least mxPathname
91e0: 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65  +1 bytes for the
91f0: 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65  .** output buffe
9200: 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e  r xFullPathname.
9210: 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65    The exact size
9220: 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   of the output b
9230: 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f  uffer.** is also
9240: 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72   passed as a par
9250: 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20  ameter to both  
9260: 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20  methods. If the 
9270: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
9280: 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e   is not large en
9290: 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41  ough, [SQLITE_CA
92a0: 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62  NTOPEN] should b
92b0: 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63  e returned. Sinc
92c0: 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e  e this is.** han
92d0: 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20  dled as a fatal 
92e0: 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c  error by SQLite,
92f0: 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74   vfs implementat
9300: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65  ions should ende
9310: 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65  avor.** to preve
9320: 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69  nt this by setti
9330: 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f  ng mxPathname to
9340: 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20   a sufficiently 
9350: 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a  large value..**.
9360: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
9370: 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20  ss(), xSleep(), 
9380: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20  xCurrentTime(), 
9390: 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65  and xCurrentTime
93a0: 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72  Int64().** inter
93b0: 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74  faces are not st
93c0: 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66  rictly a part of
93d0: 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c   the filesystem,
93e0: 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a   but they are.**
93f0: 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65   included in the
9400: 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66   VFS structure f
9410: 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e  or completeness.
9420: 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
9430: 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61  ess() function a
9440: 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72  ttempts to retur
9450: 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a  n nBytes bytes.*
9460: 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74  * of good-qualit
9470: 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  y randomness int
9480: 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74  o zOut.  The ret
9490: 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  urn value is.** 
94a0: 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65  the actual numbe
94b0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61  r of bytes of ra
94c0: 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65  ndomness obtaine
94d0: 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70  d..** The xSleep
94e0: 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73  () method causes
94f0: 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72   the calling thr
9500: 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72  ead to sleep for
9510: 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65   at.** least the
9520: 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f   number of micro
9530: 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20  seconds given.  
9540: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
9550: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
9560: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
9570: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
9580: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
9590: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
95a0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
95b0: 6c 75 65 2e 0a 2a 2a 20 54 68 65 20 78 43 75 72  lue..** The xCur
95c0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
95d0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
95e0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
95f0: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
9600: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 65   Number multiple
9610: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
9620: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
9630: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
9640: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
9650: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
9660: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
9670: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
9680: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
9690: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
96a0: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
96b0: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
96c0: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
96d0: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
96e0: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
96f0: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
9700: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
9710: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
9720: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
9730: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
9740: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
9750: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2f 0a 74  navailable..*/.t
9760: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
9770: 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65  lite3_vfs sqlite
9780: 33 5f 76 66 73 3b 0a 73 74 72 75 63 74 20 73 71  3_vfs;.struct sq
9790: 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
97a0: 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
97b0: 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
97c0: 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
97d0: 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 32 29  er (currently 2)
97e0: 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
97f0: 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
9800: 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
9810: 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
9820: 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
9830: 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
9840: 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
9850: 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
9860: 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
9870: 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
9880: 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
9890: 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
98a0: 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
98b0: 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
98c0: 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
98d0: 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
98e0: 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
98f0: 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
9900: 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
9910: 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
9920: 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
9930: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
9940: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
9950: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
9960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
9970: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
9980: 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
9990: 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
99a0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
99b0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
99c0: 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
99d0: 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
99e0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
99f0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
9a00: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
9a10: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
9a20: 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
9a30: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
9a40: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
9a50: 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
9a60: 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
9a70: 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
9a80: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9a90: 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
9aa0: 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
9ab0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
9ac0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
9ad0: 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
9ae0: 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
9af0: 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
9b00: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
9b10: 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
9b20: 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
9b30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
9b40: 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
9b50: 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
9b60: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
9b70: 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
9b80: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
9b90: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9ba0: 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
9bb0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
9bc0: 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
9bd0: 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
9be0: 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
9bf0: 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
9c00: 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
9c10: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
9c20: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
9c30: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
9c40: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
9c50: 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
9c60: 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
9c70: 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
9c80: 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
9c90: 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
9ca0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
9cb0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
9cc0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
9cd0: 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
9ce0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
9cf0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
9d00: 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
9d10: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
9d20: 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
9d30: 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62  New fields may b
9d40: 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69  e appended in fi
9d50: 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20  gure versions.  
9d60: 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a  The iVersion.  *
9d70: 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63  * value will inc
9d80: 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20  rement whenever 
9d90: 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20  this happens. . 
9da0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
9db0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
9dc0: 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46  r the xAccess VF
9dd0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
9de0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
9df0: 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73  stants can be us
9e00: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
9e10: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
9e20: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
9e30: 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  od of an [sqlite
9e40: 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
9e50: 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a  They determine.*
9e60: 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70  * what kind of p
9e70: 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78  ermissions the x
9e80: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73  Access method is
9e90: 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a   looking for..**
9ea0: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
9eb0: 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20  ESS_EXISTS, the 
9ec0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
9ed0: 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20  * simply checks 
9ee0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
9ef0: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68   exists..** With
9f00: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
9f10: 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41  EADWRITE, the xA
9f20: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
9f30: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
9f40: 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f  he named directo
9f50: 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61  ry is both reada
9f60: 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65  ble and writable
9f70: 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f  .** (in other wo
9f80: 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61  rds, if files ca
9f90: 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f  n be added, remo
9fa0: 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64  ved, and renamed
9fb0: 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64   within.** the d
9fc0: 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68  irectory)..** Th
9fd0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
9fe0: 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61  READWRITE consta
9ff0: 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  nt is currently 
a000: 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65  used only by the
a010: 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f  .** [temp_store_
a020: 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61  directory pragma
a030: 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63  ], though this c
a040: 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61  ould change in a
a050: 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61   future.** relea
a060: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
a070: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
a080: 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41  ESS_READ, the xA
a090: 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20  ccess method.** 
a0a0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74  checks whether t
a0b0: 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61  he file is reada
a0c0: 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45  ble.  The SQLITE
a0d0: 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e  _ACCESS_READ con
a0e0: 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72  stant is.** curr
a0f0: 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68  ently unused, th
a100: 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65  ough it might be
a110: 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72   used in a futur
a120: 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
a130: 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
a140: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
a150: 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65  _EXISTS    0.#de
a160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
a170: 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20  SS_READWRITE 1  
a180: 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47   /* Used by PRAG
a190: 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  MA temp_store_di
a1a0: 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69  rectory */.#defi
a1b0: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
a1c0: 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f  _READ      2   /
a1d0: 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  * Unused */../*.
a1e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
a1f0: 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c  gs for the xShmL
a200: 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ock VFS method.*
a210: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
a220: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  er constants def
a230: 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20  ine the various 
a240: 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f  locking operatio
a250: 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79  ns.** allowed by
a260: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   the xShmLock me
a270: 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  thod of [sqlite3
a280: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54  _io_methods].  T
a290: 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  he.** following 
a2a0: 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67  are the only leg
a2b0: 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  al combinations 
a2c0: 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a  of flags to the.
a2d0: 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  ** xShmLock meth
a2e0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
a2f0: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
a300: 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
a310: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
a320: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
a330: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
a340: 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
a350: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
a360: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
a370: 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
a380: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
a390: 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
a3a0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
a3b0: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  </ul>.**.** When
a3c0: 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20   unlocking, the 
a3d0: 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45  same SHARED or E
a3e0: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75  XCLUSIVE flag mu
a3f0: 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61  st be supplied a
a400: 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e  s.** was given n
a410: 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  o the correspond
a420: 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a  ing lock.  .**.*
a430: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
a440: 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69  ethod can transi
a450: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c  tion between unl
a460: 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44  ocked and SHARED
a470: 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75   or.** between u
a480: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c  nlocked and EXCL
a490: 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f  USIVE.  It canno
a4a0: 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  t transition bet
a4b0: 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61  ween SHARED.** a
a4c0: 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f  nd EXCLUSIVE..*/
a4d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a4e0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  SHM_UNLOCK      
a4f0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
a500: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20  E_SHM_LOCK      
a510: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
a520: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20  ITE_SHM_SHARED  
a530: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
a540: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
a550: 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20  IVE    8../*.** 
a560: 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75  CAPI3REF: Maximu
a570: 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78  m xShmLock index
a580: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
a590: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73  ock method on [s
a5a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
a5b0: 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65  s] may use value
a5c0: 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61  s.** between 0 a
a5d0: 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f  nd this upper bo
a5e0: 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73  und as its "offs
a5f0: 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  et" argument..**
a600: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
a610: 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65   will never atte
a620: 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f  mpt to acquire o
a630: 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c  r release a.** l
a640: 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74  ock outside of t
a650: 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65  his range.*/.#de
a660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
a670: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a  NLOCK        8..
a680: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a690: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
a6a0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
a6b0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
a6c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
a6d0: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
a6e0: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
a6f0: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
a700: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
a710: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
a720: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
a730: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
a740: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
a750: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a760: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
a770: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
a780: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
a790: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
a7a0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
a7b0: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
a7c0: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
a7d0: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
a7e0: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
a7f0: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
a800: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
a810: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
a820: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
a830: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
a840: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a850: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
a860: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
a870: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
a880: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
a890: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
a8a0: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
a8b0: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
a8c0: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
a8d0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
a8e0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
a8f0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
a900: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
a910: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
a920: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
a930: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
a940: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
a950: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a960: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
a970: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
a980: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
a990: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
a9a0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
a9b0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
a9c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
a9d0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
a9e0: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
a9f0: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
aa00: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
aa10: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
aa20: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
aa30: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
aa40: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
aa50: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
aa60: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
aa70: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
aa80: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
aa90: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
aaa0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
aab0: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
aac0: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
aad0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
aae0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
aaf0: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
ab00: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
ab10: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
ab20: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
ab30: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
ab40: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
ab50: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
ab60: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
ab70: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
ab80: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
ab90: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
aba0: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
abb0: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
abc0: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
abd0: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
abe0: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
abf0: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
ac00: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
ac10: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
ac20: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
ac30: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
ac40: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
ac50: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
ac60: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
ac70: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
ac80: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
ac90: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
aca0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
acb0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
acc0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
acd0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
ace0: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
acf0: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
ad00: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ad10: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
ad20: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
ad30: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
ad40: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
ad50: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
ad60: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
ad70: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
ad80: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
ad90: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
ada0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
adb0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
adc0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
add0: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
ade0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
adf0: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
ae00: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
ae10: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
ae20: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
ae30: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
ae40: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
ae50: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
ae60: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
ae70: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
ae80: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
ae90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
aea0: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
aeb0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
aec0: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
aed0: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
aee0: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
aef0: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
af00: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
af10: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
af20: 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
af30: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
af40: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
af50: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
af60: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
af70: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
af80: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
af90: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
afa0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
afb0: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
afc0: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
afd0: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
afe0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
aff0: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
b000: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
b010: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
b020: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
b030: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
b040: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
b050: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
b060: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
b070: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
b080: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b090: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
b0a0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
b0b0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
b0c0: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
b0d0: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
b0e0: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
b0f0: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
b100: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
b110: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
b120: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
b130: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
b140: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
b150: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
b160: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
b170: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
b180: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
b190: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
b1a0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
b1b0: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
b1c0: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
b1d0: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
b1e0: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
b1f0: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
b200: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
b210: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
b220: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
b230: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
b240: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
b250: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
b260: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
b270: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
b280: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
b290: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
b2a0: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
b2b0: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
b2c0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
b2d0: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
b2e0: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
b2f0: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
b300: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
b310: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
b320: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
b330: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
b340: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
b350: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
b360: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
b370: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
b380: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
b390: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
b3a0: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
b3b0: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
b3c0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
b3d0: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
b3e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b3f0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
b400: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
b410: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
b420: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
b430: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
b440: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
b450: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
b460: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
b470: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
b480: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
b490: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
b4a0: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
b4b0: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
b4c0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
b4d0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
b4e0: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
b4f0: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
b500: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
b510: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
b520: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
b530: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
b540: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
b550: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
b560: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
b570: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
b580: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
b590: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
b5a0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
b5b0: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
b5c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
b5d0: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
b5e0: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
b5f0: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
b600: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
b610: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
b620: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
b630: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
b640: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
b650: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
b660: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
b670: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
b680: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
b690: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
b6a0: 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
b6b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
b6c0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
b6d0: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
b6e0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
b6f0: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
b700: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
b710: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
b720: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
b730: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
b740: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
b750: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b760: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
b770: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
b780: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
b790: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
b7a0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
b7b0: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
b7c0: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
b7d0: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
b7e0: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
b7f0: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
b800: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
b810: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
b820: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
b830: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
b840: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
b850: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
b860: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
b870: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
b880: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
b890: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
b8a0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
b8b0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
b8c0: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
b8d0: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
b8e0: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
b8f0: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
b900: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
b910: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
b920: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
b930: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
b940: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
b950: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
b960: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
b970: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
b980: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
b990: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
b9a0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
b9b0: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
b9c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
b9d0: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
b9e0: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
b9f0: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
ba00: 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
ba10: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
ba20: 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
ba30: 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
ba40: 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
ba50: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
ba60: 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
ba70: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
ba80: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
ba90: 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
baa0: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
bab0: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
bac0: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
bad0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
bae0: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
baf0: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
bb00: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
bb10: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
bb20: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
bb30: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
bb40: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r.** [SQLITE_CON
bb50: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
bb60: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
bb70: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
bb80: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
bb90: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
bba0: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
bbb0: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
bbc0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
bbd0: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
bbe0: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   on the [SQLITE_
bbf0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
bc00: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
bc10: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
bc20: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
bc30: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
bc40: 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
bc50: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
bc60: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
bc70: 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
bc80: 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
bc90: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
bca0: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
bcb0: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
bcc0: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
bcd0: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
bce0: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
bcf0: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
bd00: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
bd10: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
bd20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
bd30: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
bd40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
bd50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
bd60: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
bd70: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
bd80: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
bd90: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
bda0: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
bdb0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
bdc0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
bdd0: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
bde0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
bdf0: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
be00: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
be10: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
be20: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
be30: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
be40: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
be50: 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73  ment).  The.** s
be60: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
be70: 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f  () interface sho
be80: 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  uld only be used
be90: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
bea0: 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  er.** the databa
beb0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
bec0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
bed0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
bee0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
bef0: 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  n16()], or [sqli
bf00: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
bf10: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f   .**.** The seco
bf20: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
bf30: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
bf40: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
bf50: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
bf60: 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74  on verb - an int
bf70: 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 69  eger code that i
bf80: 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a  ndicates what.**
bf90: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
bfa0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
bfb0: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
bfc0: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65  nfigured..** The
bfd0: 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72   only choice for
bfe0: 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b   this value is [
bff0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
c000: 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e  LOOKASIDE]..** N
c010: 65 77 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b  ew verbs are lik
c020: 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64 20  ely to be added 
c030: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
c040: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
c050: 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   Additional argu
c060: 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20  ments depend on 
c070: 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  the verb..**.** 
c080: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
c090: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
c0a0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
c0b0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
c0c0: 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
c0d0: 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
c0e0: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
c0f0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
c100: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
c110: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
c120: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
c130: 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
c140: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
c150: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
c160: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
c170: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
c180: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
c190: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
c1a0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
c1b0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
c1c0: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
c1d0: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
c1e0: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
c1f0: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
c200: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
c210: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
c220: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
c230: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
c240: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
c250: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
c260: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
c270: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
c280: 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
c290: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
c2a0: 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
c2b0: 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
c2c0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
c2d0: 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
c2e0: 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
c2f0: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
c300: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
c310: 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
c320: 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
c330: 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
c340: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
c350: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
c360: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
c370: 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
c380: 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
c390: 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
c3a0: 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
c3b0: 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
c3c0: 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
c3d0: 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
c3e0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
c3f0: 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
c400: 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
c410: 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
c420: 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
c430: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
c440: 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
c450: 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
c460: 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
c470: 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
c480: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
c490: 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
c4a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
c4b0: 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
c4c0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
c4d0: 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
c4e0: 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
c4f0: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
c500: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
c510: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
c520: 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
c530: 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
c540: 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
c550: 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
c560: 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
c570: 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
c580: 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
c590: 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
c5a0: 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
c5b0: 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78  he xMalloc and x
c5c0: 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
c5d0: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
c5e0: 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ** malloc() and 
c5f0: 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
c600: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
c610: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
c620: 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65   The xRealloc me
c630: 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c  thod must work l
c640: 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72  ike realloc() fr
c650: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
c660: 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74  C library.** wit
c670: 68 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20  h the exception 
c680: 74 68 61 74 20 69 66 20 74 68 65 20 73 65 63 6f  that if the seco
c690: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  nd argument to x
c6a0: 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c  Realloc is zero,
c6b0: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73  .** xRealloc mus
c6c0: 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69  t be a no-op - i
c6d0: 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f  t must not perfo
c6e0: 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f  rm any allocatio
c6f0: 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  n or.** dealloca
c700: 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67  tion.  ^SQLite g
c710: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
c720: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
c730: 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
c740: 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
c750: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
c760: 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
c770: 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64  xRoundup..** And
c780: 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65   so in cases whe
c790: 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61  re xRoundup alwa
c7a0: 79 73 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73  ys returns a pos
c7b0: 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a  itive number,.**
c7c0: 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65   xRealloc can pe
c7d0: 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73  rform exactly as
c7e0: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69   the standard li
c7f0: 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20  brary realloc() 
c800: 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20  and.** still be 
c810: 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69  in compliance wi
c820: 74 68 20 74 68 69 73 20 73 70 65 63 69 66 69 63  th this specific
c830: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  ation..**.** xSi
c840: 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
c850: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
c860: 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
c870: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
c880: 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
c890: 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
c8a0: 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
c8b0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
c8c0: 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
c8d0: 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
c8e0: 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
c8f0: 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
c900: 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
c910: 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
c920: 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
c930: 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
c940: 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
c950: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c960: 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
c970: 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
c980: 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
c990: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
c9a0: 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
c9b0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
c9c0: 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
c9d0: 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
c9e0: 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
c9f0: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
ca00: 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
ca10: 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
ca20: 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
ca30: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ca40: 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
ca50: 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
ca60: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
ca70: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
ca80: 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
ca90: 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
caa0: 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
cab0: 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
cac0: 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
cad0: 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
cae0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
caf0: 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
cb00: 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
cb10: 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
cb20: 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46  y allocator.  (F
cb30: 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
cb40: 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
cb50: 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
cb60: 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
cb70: 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
cb80: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
cb90: 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
cba0: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
cbb0: 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
cbc0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
cbd0: 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
cbe0: 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
cbf0: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
cc00: 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
cc10: 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
cc20: 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
cc30: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
cc40: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
cc50: 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
cc60: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
cc70: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
cc80: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
cc90: 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
cca0: 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
ccb0: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
ccc0: 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
ccd0: 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
cce0: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
ccf0: 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
cd00: 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
cd10: 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
cd20: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
cd30: 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
cd40: 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
cd50: 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
cd60: 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
cd70: 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
cd80: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
cd90: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
cda0: 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
cdb0: 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
cdc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
cdd0: 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
cde0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
cdf0: 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
ce00: 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
ce10: 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
ce20: 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
ce30: 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
ce40: 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
ce50: 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
ce60: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
ce70: 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
ce80: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
ce90: 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
cea0: 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
ceb0: 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
cec0: 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
ced0: 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
cee0: 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
cef0: 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
cf00: 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
cf10: 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
cf20: 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
cf30: 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
cf40: 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
cf50: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
cf60: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
cf70: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
cf80: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
cf90: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
cfa0: 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
cfb0: 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
cfc0: 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
cfd0: 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
cfe0: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
cff0: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
d000: 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
d010: 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
d020: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
d030: 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
d040: 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
d050: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
d060: 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
d070: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
d080: 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
d090: 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
d0a0: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
d0b0: 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
d0c0: 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
d0d0: 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
d0e0: 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
d0f0: 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
d100: 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
d110: 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
d120: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
d130: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
d140: 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
d150: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
d160: 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
d170: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
d180: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
d190: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
d1a0: 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
d1b0: 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
d1c0: 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
d1d0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
d1e0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
d1f0: 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
d200: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
d210: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
d220: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
d230: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
d240: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
d250: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
d260: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
d270: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
d280: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
d290: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
d2a0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
d2b0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
d2c0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
d2d0: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
d2e0: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
d2f0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
d300: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
d310: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
d320: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
d330: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
d340: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
d350: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
d360: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
d370: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
d380: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
d390: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
d3a0: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
d3b0: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
d3c0: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
d3d0: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
d3e0: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
d3f0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
d400: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
d410: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
d420: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
d430: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
d440: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
d450: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
d460: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
d470: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
d480: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
d490: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
d4a0: 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
d4b0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
d4c0: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
d4d0: 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
d4e0: 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
d4f0: 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
d500: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
d510: 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
d520: 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
d530: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
d540: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
d550: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
d560: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
d570: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
d580: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
d590: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
d5a0: 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
d5b0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
d5c0: 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
d5d0: 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
d5e0: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
d5f0: 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
d600: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
d610: 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
d620: 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
d630: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
d640: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
d650: 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
d660: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
d670: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d680: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
d690: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
d6a0: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
d6b0: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
d6c0: 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
d6d0: 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
d6e0: 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
d6f0: 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
d700: 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
d710: 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
d720: 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
d730: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
d740: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
d750: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
d760: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
d770: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
d780: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
d790: 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
d7a0: 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
d7b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
d7c0: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
d7d0: 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
d7e0: 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
d7f0: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
d800: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
d810: 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
d820: 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
d830: 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
d840: 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
d850: 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
d860: 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
d870: 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
d880: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
d890: 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
d8a0: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
d8b0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d8c0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
d8d0: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
d8e0: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
d8f0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
d900: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
d910: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
d920: 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
d930: 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
d940: 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
d950: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d960: 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
d970: 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
d980: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
d990: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
d9a0: 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
d9b0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
d9c0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d9d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
d9e0: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
d9f0: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
da00: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
da10: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
da20: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
da30: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
da40: 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
da50: 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
da60: 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
da70: 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
da80: 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
da90: 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
daa0: 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
dab0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
dac0: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
dad0: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
dae0: 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
daf0: 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
db00: 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
db10: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
db20: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
db30: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
db40: 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
db50: 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
db60: 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
db70: 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
db80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
db90: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
dba0: 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
dbb0: 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
dbc0: 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
dbd0: 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
dbe0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
dbf0: 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
dc00: 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
dc10: 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
dc20: 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
dc30: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
dc40: 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
dc50: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
dc60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
dc70: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
dc80: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
dc90: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
dca0: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
dcb0: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
dcc0: 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
dcd0: 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
dce0: 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
dcf0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
dd00: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
dd10: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
dd20: 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
dd30: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
dd40: 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
dd50: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
dd60: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
dd70: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
dd80: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
dd90: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
dda0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
ddb0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
ddc0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
ddd0: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
dde0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
ddf0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
de00: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
de10: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
de20: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
de30: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
de40: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
de50: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
de60: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
de70: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
de80: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
de90: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
dea0: 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
deb0: 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
dec0: 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
ded0: 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
dee0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
def0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
df00: 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
df10: 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
df20: 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
df30: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
df40: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
df50: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
df60: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
df70: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
df80: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
df90: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
dfa0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
dfb0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
dfc0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
dfd0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
dfe0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
dff0: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
e000: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
e010: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
e020: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
e030: 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
e040: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
e050: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
e060: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
e070: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
e080: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
e090: 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
e0a0: 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
e0b0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
e0c0: 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
e0d0: 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
e0e0: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
e0f0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
e100: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
e110: 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
e120: 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
e130: 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
e140: 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
e150: 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
e160: 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
e170: 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
e180: 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
e190: 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
e1a0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
e1b0: 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
e1c0: 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
e1d0: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
e1e0: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
e1f0: 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
e200: 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
e210: 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
e220: 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
e230: 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
e240: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
e250: 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
e260: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
e270: 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
e280: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
e290: 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
e2a0: 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  t()].**   <li> [
e2b0: 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
e2c0: 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
e2d0: 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
e2e0: 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
e2f0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
e300: 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
e310: 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
e320: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
e330: 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
e340: 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
e350: 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
e360: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
e370: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
e380: 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
e390: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e3a0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
e3b0: 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
e3c0: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
e3d0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
e3e0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
e3f0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
e400: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
e410: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
e420: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
e430: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
e440: 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
e450: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
e460: 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
e470: 20 74 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f   the scrach allo
e480: 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
e490: 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
e4a0: 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
e4b0: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
e4c0: 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
e4d0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
e4e0: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
e4f0: 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
e500: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
e510: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
e520: 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70   of 16. The sz p
e530: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
e540: 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a  be a few bytes.*
e550: 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  * larger than th
e560: 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68  e actual scratch
e570: 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
e580: 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20  due to internal 
e590: 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65  overhead..** The
e5a0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
e5b0: 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
e5c0: 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
e5d0: 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
e5e0: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
e5f0: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
e600: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
e610: 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
e620: 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
e630: 62 75 66 66 65 72 20 70 65 72 20 74 68 72 65 61  buffer per threa
e640: 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75  d.  So.** N shou
e650: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65  ld be set to the
e660: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
e670: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
e680: 61 64 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ads.  ^SQLite wi
e690: 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 72 65 71 75  ll.** never requ
e6a0: 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75  ire a scratch bu
e6b0: 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
e6c0: 65 20 74 68 61 6e 20 36 20 74 69 6d 65 73 20 74  e than 6 times t
e6d0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70  he database.** p
e6e0: 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51  age size. ^If SQ
e6f0: 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
e700: 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 63 72 61   additional scra
e710: 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
e720: 64 20 0a 2a 2a 20 77 68 61 74 20 69 73 20 70 72  d .** what is pr
e730: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
e740: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e750: 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
e760: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
e770: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
e780: 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
e790: 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
e7a0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
e7b0: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
e7c0: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
e7d0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
e7e0: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
e7f0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
e800: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
e810: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
e820: 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
e830: 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
e840: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
e850: 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  emenation.  .** 
e860: 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
e870: 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
e880: 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
e890: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
e8a0: 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
e8b0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
e8c0: 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
e8d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
e8e0: 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  ACHE option..** 
e8f0: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
e900: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
e910: 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e  s option: A poin
e920: 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c  ter to 8-byte al
e930: 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c  igned.** memory,
e940: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
e950: 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73  h page buffer (s
e960: 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
e970: 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e  er of pages (N).
e980: 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
e990: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
e9a0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
e9b0: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
e9c0: 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
e9d0: 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
e9e0: 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c  12 and 32768) pl
e9f0: 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72  us a little extr
ea00: 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  a for each.** pa
ea10: 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
ea20: 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a   page header siz
ea30: 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79  e is 20 to 40 by
ea40: 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  tes depending on
ea50: 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63  .** the host arc
ea60: 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20  hitecture.  ^It 
ea70: 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
ea80: 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
ea90: 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f  ed memory,.** to
eaa0: 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c   make sz a littl
eab0: 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68  e too large.  Th
eac0: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
ead0: 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
eae0: 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
eaf0: 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
eb00: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
eb10: 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
eb20: 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
eb30: 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
eb40: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
eb50: 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
eb60: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
eb70: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
eb80: 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
eb90: 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e  dds to cache.  ^
eba0: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
ebb0: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
ebc0: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
ebd0: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
ebe0: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
ebf0: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
ec00: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
ec10: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
ec20: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
ec30: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
ec40: 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65  .** ^The impleme
ec50: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73  ntation might us
ec60: 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  e one or more of
ec70: 20 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 74   the N buffers t
ec80: 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72  o hold .** memor
ec90: 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66  y accounting inf
eca0: 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f  ormation. The po
ecb0: 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
ecc0: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
ecd0: 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
ece0: 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
ecf0: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
ed00: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
ed10: 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
ed20: 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
ed30: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
ed40: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
ed50: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
ed60: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
ed70: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
ed80: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
ed90: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
eda0: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
edb0: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
edc0: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
edd0: 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
ede0: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
edf0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
ee00: 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
ee10: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
ee20: 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
ee30: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
ee40: 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
ee50: 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
ee60: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
ee70: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
ee80: 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
ee90: 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
eea0: 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
eeb0: 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
eec0: 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
eed0: 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
eee0: 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
eef0: 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
ef00: 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
ef10: 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
ef20: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
ef30: 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
ef40: 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
ef50: 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
ef60: 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
ef70: 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
ef80: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
ef90: 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
efa0: 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
efb0: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68  ot NULL and eith
efc0: 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
efd0: 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a  E_MEMSYS3] or.**
efe0: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
eff0: 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66  MEMSYS5] are def
f000: 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61  ined, then the a
f010: 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
f020: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
f030: 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
f040: 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
f050: 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
f060: 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
f070: 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
f080: 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
f090: 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
f0a0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
f0b0: 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
f0c0: 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
f0d0: 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
f0e0: 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
f0f0: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
f100: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
f110: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
f120: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
f130: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
f140: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
f150: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
f160: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
f170: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
f180: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
f190: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
f1a0: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
f1b0: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
f1c0: 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
f1d0: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
f1e0: 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
f1f0: 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
f200: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
f210: 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
f220: 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
f230: 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
f240: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
f250: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
f260: 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
f270: 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
f280: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f290: 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
f2a0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
f2b0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
f2c0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
f2d0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
f2e0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
f2f0: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
f300: 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
f310: 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
f320: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
f330: 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
f340: 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
f350: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f360: 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
f370: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
f380: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
f390: 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
f3a0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
f3b0: 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
f3c0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
f3d0: 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
f3e0: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
f3f0: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
f400: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
f410: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
f420: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
f430: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
f440: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
f450: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
f460: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
f470: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
f480: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
f490: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
f4a0: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
f4b0: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
f4c0: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
f4d0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
f4e0: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
f4f0: 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
f500: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
f510: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
f520: 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
f530: 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
f540: 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
f550: 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
f560: 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
f570: 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
f580: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
f590: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
f5a0: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
f5b0: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
f5c0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
f5d0: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
f5e0: 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
f5f0: 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
f600: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
f610: 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
f620: 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
f630: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
f640: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
f650: 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
f660: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
f670: 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
f680: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
f690: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
f6a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
f6b0: 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
f6c0: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
f6d0: 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
f6e0: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
f6f0: 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
f700: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
f710: 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
f720: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
f730: 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
f740: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
f750: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
f760: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
f770: 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
f780: 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
f790: 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
f7a0: 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
f7b0: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
f7c0: 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
f7d0: 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
f7e0: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
f7f0: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
f800: 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
f810: 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
f820: 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
f830: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
f840: 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
f850: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
f860: 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
f870: 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
f880: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
f890: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
f8a0: 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
f8b0: 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
f8c0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f8d0: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c  E_CONFIG_PCACHE<
f8e0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
f8f0: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f900: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
f910: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
f920: 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
f930: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
f940: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20  ethods] object. 
f950: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
f960: 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72  cifies the inter
f970: 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73  face.** to a cus
f980: 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
f990: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e  mplementation.)^
f9a0: 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
f9b0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
f9c0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73   object and uses
f9d0: 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63   it for page cac
f9e0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
f9f0: 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tions.</dd>.**.*
fa00: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
fa10: 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64  FIG_GETPCACHE</d
fa20: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
fa30: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
fa40: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
fa50: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
fa60: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
fa70: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
fa80: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53  hods] object.  S
fa90: 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
faa0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
fab0: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
fac0: 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
fad0: 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
fae0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
faf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f  ITE_CONFIG_LOG</
fb00: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
fb10: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
fb20: 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
fb30: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
fb40: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
fb50: 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
fb60: 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
fb70: 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
fb80: 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
fb90: 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
fba0: 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
fbb0: 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
fbc0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
fbd0: 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
fbe0: 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
fbf0: 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
fc00: 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
fc10: 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
fc20: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
fc30: 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
fc40: 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
fc50: 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
fc60: 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
fc70: 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
fc80: 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
fc90: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
fca0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
fcb0: 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
fcc0: 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
fcd0: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
fce0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
fcf0: 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
fd00: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
fd10: 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
fd20: 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
fd30: 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
fd40: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
fd50: 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
fd60: 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
fd70: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
fd80: 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
fd90: 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
fda0: 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
fdb0: 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
fdc0: 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
fdd0: 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
fde0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
fdf0: 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
fe00: 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
fe10: 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
fe20: 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
fe30: 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
fe40: 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
fe50: 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
fe60: 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
fe70: 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
fe80: 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
fe90: 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
fea0: 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
feb0: 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
fec0: 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
fed0: 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
fee0: 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
fef0: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
ff00: 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
ff10: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
ff20: 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
ff30: 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
ff40: 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
ff50: 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
ff60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
ff70: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
ff80: 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
ff90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ffa0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
ffb0: 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
ffc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ffd0: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
ffe0: 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
fff0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10000 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
10010 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
10020 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
10030 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
10040 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
10050 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
10060 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
10070 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
10080 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
10090 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
100a0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
100b0 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
100c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
100d0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
100e0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
100f0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
10100 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10110 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
10120 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
10130 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
10140 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10150 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
10160 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
10170 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
10180 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
10190 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
101a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
101b0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
101c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
101d0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
101e0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
101f0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
10200 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
10210 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
10220 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
10230 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
10240 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
10250 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
10260 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
10270 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
10280 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
10290 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
102a0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
102b0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
102c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
102d0 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
102e0 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  5  /* sqlite3_pc
102f0 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
10300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10310 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
10320 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
10330 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a  , void* */../*.*
10340 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
10350 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
10360 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
10370 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
10380 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
10390 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
103a0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
103b0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
103c0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
103d0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
103e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
103f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
10400 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
10410 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
10420 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10430 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
10440 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
10450 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
10460 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
10470 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
10480 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
10490 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
104a0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
104b0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
104c0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
104d0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
104e0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
104f0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
10500 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
10510 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
10520 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
10530 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
10540 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
10550 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
10560 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
10570 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
10580 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
10590 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
105a0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
105b0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
105c0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
105d0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
105e0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
105f0 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
10600 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
10610 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
10620 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
10630 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
10640 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
10650 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
10660 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
10670 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
10680 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
10690 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
106a0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
106b0 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20  er to an memory 
106c0 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
106d0 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
106e0 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
106f0 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
10700 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
10710 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
10720 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
10730 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
10740 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
10750 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
10760 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
10770 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
10780 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
10790 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
107a0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
107b0 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
107c0 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
107d0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
107e0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
107f0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
10800 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
10810 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
10820 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10830 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
10840 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
10850 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
10860 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
10870 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
10880 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
10890 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
108a0 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
108b0 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
108c0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
108d0 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
108e0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
108f0 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
10900 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
10910 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
10920 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
10930 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a  e next smaller.*
10940 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  * multiple of 8.
10950 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
10960 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
10970 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  SIDE]</dd>.**.**
10980 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
10990 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
109a0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
109b0 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
109c0 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a  t int */.../*.**
109d0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
109e0 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
109f0 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
10a00 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
10a10 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
10a20 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
10a30 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
10a40 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
10a50 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
10a60 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
10a70 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
10a80 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
10a90 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
10aa0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
10ab0 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
10ac0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
10ad0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
10ae0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
10af0 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
10b00 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
10b10 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
10b20 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
10b30 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
10b40 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
10b50 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
10b60 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
10b70 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
10b80 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
10b90 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
10ba0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
10bb0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
10bc0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
10bd0 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
10be0 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
10bf0 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
10c00 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
10c10 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
10c20 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
10c30 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
10c40 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
10c50 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
10c60 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
10c70 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
10c80 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
10c90 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
10ca0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
10cb0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
10cc0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
10cd0 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73  owid] of the mos
10ce0 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
10cf0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
10d00 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
10d10 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
10d20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10d30 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
10d40 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
10d50 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
10d60 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
10d70 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
10d80 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
10d90 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
10da0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
10db0 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
10dc0 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
10dd0 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  n a trigger, the
10de0 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
10df0 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
10e00 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64   row is returned
10e10 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
10e20 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
10e30 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69  trigger is runni
10e40 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
10e50 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d  the trigger term
10e60 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75  inates, the valu
10e70 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
10e80 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65  is routine.** re
10e90 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73  verts to the las
10ea0 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64  t value inserted
10eb0 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
10ec0 67 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  ger fired.)^.**.
10ed0 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
10ee0 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
10ef0 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
10f00 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
10f10 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
10f20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
10f30 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
10f40 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
10f50 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
10f60 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
10f70 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
10f80 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
10f90 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
10fa0 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
10fb0 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
10fc0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
10fd0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
10fe0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
10ff0 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
11000 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
11010 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
11020 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
11030 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
11040 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
11050 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
11060 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
11070 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
11080 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
11090 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
110a0 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
110b0 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
110c0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
110d0 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
110e0 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
110f0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
11100 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
11110 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
11120 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
11130 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
11140 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
11150 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
11160 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
11170 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
11180 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
11190 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
111a0 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
111b0 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
111c0 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
111d0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
111e0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
111f0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
11200 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
11210 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
11220 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
11230 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
11240 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
11250 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
11260 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
11270 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
11280 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
11290 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
112a0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
112b0 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
112c0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
112d0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
112e0 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
112f0 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
11300 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
11310 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
11320 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
11330 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
11340 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
11350 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
11360 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
11370 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
11380 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
11390 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
113a0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
113b0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
113c0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
113d0 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
113e0 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
113f0 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
11400 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
11410 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
11420 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
11430 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
11440 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
11450 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11460 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
11470 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
11480 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
11490 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
114a0 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
114b0 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
114c0 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
114d0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
114e0 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
114f0 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
11500 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
11510 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
11520 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
11530 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
11540 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
11550 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
11560 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
11570 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
11580 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
11590 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
115a0 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
115b0 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
115c0 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
115d0 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
115e0 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
115f0 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
11600 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
11610 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
11620 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
11630 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
11640 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
11650 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
11660 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
11670 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
11680 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
11690 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
116a0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
116b0 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
116c0 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
116d0 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
116e0 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
116f0 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
11700 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
11710 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
11720 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
11730 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
11740 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
11750 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
11760 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
11770 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
11780 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
11790 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
117a0 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
117b0 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
117c0 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
117d0 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
117e0 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
117f0 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
11800 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
11810 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
11820 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
11830 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
11840 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
11850 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
11860 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
11870 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
11880 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
11890 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
118a0 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
118b0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
118c0 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
118d0 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
118e0 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
118f0 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
11900 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
11910 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
11920 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
11930 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
11940 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
11950 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
11960 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
11970 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
11980 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
11990 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
119a0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
119b0 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
119c0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
119d0 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
119e0 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
119f0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
11a00 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
11a10 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
11a20 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
11a30 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
11a40 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
11a50 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
11a60 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
11a70 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
11a80 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
11a90 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
11aa0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
11ab0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
11ac0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
11ad0 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
11ae0 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
11af0 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
11b00 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
11b10 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
11b20 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
11b30 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
11b40 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
11b50 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
11b60 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
11b70 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
11b80 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
11b90 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
11ba0 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
11bb0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
11bc0 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
11bd0 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
11be0 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
11bf0 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
11c00 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
11c10 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
11c20 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
11c30 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
11c40 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
11c50 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
11c60 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
11c70 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
11c80 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
11c90 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
11ca0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
11cb0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
11cc0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
11cd0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
11ce0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11cf0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
11d00 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
11d10 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
11d20 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
11d30 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
11d40 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
11d50 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
11d60 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
11d70 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
11d80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11d90 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
11da0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
11db0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
11dc0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
11dd0 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
11de0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
11df0 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
11e00 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
11e10 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
11e20 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
11e30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
11e40 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
11e50 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
11e60 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
11e70 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
11e80 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
11e90 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
11ea0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
11eb0 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
11ec0 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
11ed0 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
11ee0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
11ef0 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
11f00 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
11f10 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
11f20 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
11f30 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
11f40 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
11f50 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
11f60 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
11f70 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
11f80 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
11f90 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
11fa0 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
11fb0 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
11fc0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
11fd0 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
11fe0 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
11ff0 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
12000 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
12010 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
12020 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
12030 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
12040 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
12050 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
12060 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
12070 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
12080 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
12090 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
120a0 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
120b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
120c0 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
120d0 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
120e0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
120f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
12100 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
12110 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
12120 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
12130 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
12140 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
12150 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
12160 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
12170 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
12180 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
12190 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
121a0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
121b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
121c0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
121d0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
121e0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
121f0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
12200 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
12210 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
12220 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
12230 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
12240 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
12250 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
12260 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
12270 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
12280 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
12290 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
122a0 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
122b0 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
122c0 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
122d0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
122e0 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
122f0 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
12300 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
12310 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
12320 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
12330 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
12340 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
12350 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
12360 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
12370 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
12380 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
12390 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
123a0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
123b0 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
123c0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
123d0 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
123e0 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
123f0 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
12400 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
12410 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
12420 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
12430 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
12440 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
12450 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
12460 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12470 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
12480 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
12490 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
124a0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
124b0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
124c0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
124d0 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
124e0 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
124f0 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
12500 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
12510 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
12520 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
12530 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
12540 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
12550 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
12560 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
12570 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
12580 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
12590 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
125a0 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
125b0 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
125c0 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
125d0 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
125e0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
125f0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
12600 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
12610 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
12620 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
12630 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
12640 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
12650 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
12660 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
12670 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
12680 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
12690 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
126a0 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
126b0 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
126c0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
126d0 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
126e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
126f0 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
12700 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
12710 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
12720 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
12730 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
12740 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
12750 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
12760 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
12770 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
12780 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
12790 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
127a0 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
127b0 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
127c0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
127d0 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
127e0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
127f0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
12800 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
12810 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
12820 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
12830 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
12840 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
12850 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
12860 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
12870 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
12880 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
12890 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
128a0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
128b0 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
128c0 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
128d0 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
128e0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
128f0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
12900 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
12910 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
12920 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
12930 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
12940 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
12950 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
12960 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
12970 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
12980 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
12990 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
129a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
129b0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
129c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
129d0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
129e0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
129f0 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
12a00 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
12a10 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
12a20 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
12a30 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
12a40 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
12a50 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
12a60 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
12a70 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
12a80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
12a90 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
12aa0 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
12ab0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
12ac0 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
12ad0 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
12ae0 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
12af0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
12b00 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
12b10 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
12b20 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
12b30 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
12b40 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
12b50 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
12b60 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
12b70 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
12b80 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
12b90 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
12ba0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
12bb0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
12bc0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
12bd0 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
12be0 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
12bf0 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
12c00 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
12c10 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
12c20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
12c30 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
12c40 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
12c50 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
12c60 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
12c70 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
12c80 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
12c90 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
12ca0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
12cb0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
12cc0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
12cd0 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
12ce0 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
12cf0 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
12d00 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
12d10 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
12d20 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
12d30 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
12d40 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
12d50 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
12d60 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
12d70 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
12d80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
12d90 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
12da0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
12db0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
12dc0 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
12dd0 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
12de0 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
12df0 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
12e00 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
12e10 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
12e20 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12e30 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
12e40 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
12e50 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
12e60 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
12e70 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
12e80 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
12e90 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
12ea0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
12eb0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
12ec0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
12ed0 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
12ee0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
12ef0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
12f00 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
12f10 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
12f20 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
12f30 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
12f40 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
12f50 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
12f60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
12f70 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
12f80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
12f90 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
12fa0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
12fb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
12fc0 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
12fd0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
12fe0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
12ff0 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
13000 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
13010 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
13020 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
13030 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
13040 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
13050 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
13060 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13070 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
13080 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
13090 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
130a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
130b0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
130c0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
130d0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
130e0 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
130f0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
13100 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
13110 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
13120 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
13130 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
13140 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
13150 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
13160 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
13170 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
13180 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
13190 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
131a0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
131b0 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
131c0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
131d0 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
131e0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
131f0 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
13200 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
13210 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
13220 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
13230 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
13240 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
13250 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
13260 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
13270 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
13280 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
13290 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
132a0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
132b0 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
132c0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
132d0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
132e0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
132f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
13300 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
13310 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
13320 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
13330 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
13340 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
13350 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
13360 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
13370 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
13380 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
13390 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
133a0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
133b0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
133c0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
133d0 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
133e0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ed..** ^If the c
133f0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
13400 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
13410 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
13420 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
13430 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
13440 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
13450 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
13460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
13470 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
13480 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
13490 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
134a0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
134b0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
134c0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
134d0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
134e0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
134f0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
13500 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
13510 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
13520 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
13530 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
13540 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
13550 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
13560 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
13570 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
13580 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
13590 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
135a0 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
135b0 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
135c0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
135d0 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
135e0 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
135f0 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
13600 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
13610 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
13620 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
13630 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
13640 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
13650 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
13660 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
13670 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
13680 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
13690 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
136a0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
136b0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
136c0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
136d0 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
136e0 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
136f0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
13700 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
13710 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
13720 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
13730 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
13740 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
13750 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
13760 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
13770 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
13780 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
13790 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
137a0 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
137b0 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
137c0 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
137d0 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
137e0 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
137f0 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
13800 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
13810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
13820 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
13830 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
13840 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55   ^The [SQLITE_BU
13850 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
13860 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
13870 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
13880 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
13890 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
138a0 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
138b0 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
138c0 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
138d0 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
138e0 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
138f0 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
13900 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
13910 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
13920 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
13930 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
13940 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
13950 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
13960 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
13970 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
13980 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
13990 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
139a0 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
139b0 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
139c0 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
139d0 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65  ^If it is unable
139e0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
139f0 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
13a00 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
13a10 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
13a20 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
13a30 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
13a40 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
13a50 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
13a60 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
13a70 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
13a80 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
13a90 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
13aa0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
13ab0 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72  D].  ^This error
13ac0 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
13ad0 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
13ae0 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
13af0 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
13b00 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
13b10 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
13b20 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
13b30 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
13b40 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
13b50 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
13b60 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
13b70 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
13b80 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
13b90 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
13ba0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
13bb0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
13bc0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
13bd0 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
13be0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13bf0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
13c00 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
13c10 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
13c20 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
13c30 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
13c40 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
13c50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
13c60 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
13c70 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
13c80 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
13c90 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
13ca0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
13cb0 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
13cc0 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
13cd0 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
13ce0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13cf0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
13d00 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
13d10 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
13d20 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
13d30 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
13d40 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
13d50 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
13d60 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
13d70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13d80 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
13d90 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
13da0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
13db0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
13dc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
13dd0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
13de0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
13df0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
13e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
13e10 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
13e20 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
13e30 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
13e40 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
13e50 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
13e60 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
13e70 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
13e80 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
13e90 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
13ea0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
13eb0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
13ec0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
13ed0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
13ee0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
13ef0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
13f00 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
13f10 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
13f20 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
13f30 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
13f40 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
13f50 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
13f60 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
13f70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
13f80 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
13f90 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
13fa0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
13fb0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
13fc0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
13fd0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
13fe0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
13ff0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
14000 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
14010 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
14020 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
14030 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
14040 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
14050 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
14060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14070 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
14080 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
14090 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
140a0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
140b0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
140c0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
140d0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
140e0 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
140f0 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
14100 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
14110 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
14120 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
14130 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
14140 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
14150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
14160 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
14170 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
14180 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69  eries.**.** Defi
14190 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
141a0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
141b0 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
141c0 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
141d0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
141e0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
141f0 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
14200 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
14210 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
14220 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
14230 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
14240 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
14250 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
14260 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
14270 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
14280 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
14290 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
142a0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
142b0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
142c0 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
142d0 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
142e0 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
142f0 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
14300 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
14310 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
14320 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
14330 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
14340 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
14350 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
14360 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
14370 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
14380 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
14390 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
143a0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
143b0 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
143c0 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
143d0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
143e0 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
143f0 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
14400 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
14410 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
14420 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
14430 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
14440 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
14450 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
14460 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
14470 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
14480 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
14490 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
144a0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
144b0 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
144c0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
144d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
144e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
144f0 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
14500 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
14510 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
14520 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
14530 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
14540 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
14550 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
14560 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
14570 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
14580 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
14590 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
145a0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
145b0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  le()]..**.** As 
145c0 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
145d0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
145e0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
145f0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
14600 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
14610 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
14620 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
14630 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
14640 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
14650 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
14660 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
14670 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
14680 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
14690 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
146a0 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
146b0 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
146c0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
146d0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
146e0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
146f0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
14700 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
14710 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
14720 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
14730 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
14740 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
14750 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
14760 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
14770 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
14780 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
14790 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
147a0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
147b0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
147c0 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
147d0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
147e0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
147f0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
14800 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
14810 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
14820 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14830 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
14840 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
14850 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
14860 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14870 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
14880 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
14890 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
148a0 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
148b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
148c0 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
148d0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
148e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
148f0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
14900 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
14910 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
14920 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
14930 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
14940 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
14950 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
14960 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
14970 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
14980 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
14990 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
149a0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
149b0 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
149c0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
149d0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
149e0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
149f0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
14a00 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
14a10 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
14a20 20 73 68 6f 75 6c 64 20 70 61 73 73 20 74 68 65   should pass the
14a30 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
14a40 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
14a50 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
14a60 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
14a70 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
14a80 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
14a90 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
14aa0 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
14ab0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14ac0 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
14ad0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
14ae0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
14af0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
14b00 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
14b10 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
14b20 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
14b30 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
14b40 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
14b50 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
14b60 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
14b70 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
14b80 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
14b90 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
14ba0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
14bb0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
14bc0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
14bd0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
14be0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
14bf0 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
14c00 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
14c10 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
14c20 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
14c30 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
14c40 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
14c50 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
14c60 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
14c70 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
14c80 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
14c90 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
14ca0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
14cb0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
14cc0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
14cd0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
14ce0 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
14cf0 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
14d00 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
14d10 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
14d20 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
14d30 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e  te3_errmsg()].)^
14d40 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
14d50 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
14d60 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
14d70 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
14d80 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
14d90 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
14da0 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
14db0 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
14dc0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
14dd0 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
14de0 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
14df0 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
14e00 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
14e10 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
14e20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
14e30 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
14e40 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
14e50 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
14e60 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
14e70 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
14e80 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
14e90 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
14ea0 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
14eb0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
14ec0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
14ed0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
14ee0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
14ef0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
14f00 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
14f10 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
14f20 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
14f30 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
14f40 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
14f50 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
14f60 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
14f70 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
14f80 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
14f90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
14fa0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
14fb0 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
14fc0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
14fd0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
14fe0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
14ff0 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
15000 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
15010 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
15020 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
15030 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
15040 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
15050 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
15060 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
15070 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
15080 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
15090 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
150a0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
150b0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
150c0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
150d0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71  g..**.** ^(In sq
150e0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
150f0 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
15100 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
15110 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
15120 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
15130 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
15140 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
15150 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
15160 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
15170 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
15180 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
15190 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
151a0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
151b0 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
151c0 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
151d0 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
151e0 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
151f0 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
15200 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
15210 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
15220 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
15230 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
15240 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
15250 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
15260 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
15270 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
15280 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
15290 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
152a0 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
152b0 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
152c0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
152d0 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
152e0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
152f0 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
15300 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
15310 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
15320 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
15330 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
15340 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
15350 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
15360 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
15370 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
15380 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
15390 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
153a0 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
153b0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
153c0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
153d0 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
153e0 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
153f0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15400 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
15410 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
15420 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
15430 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
15440 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
15450 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
15460 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
15470 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
15480 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
15490 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
154a0 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
154b0 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
154c0 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
154d0 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
154e0 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
154f0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ters..**.** Thes
15500 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
15510 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
15520 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
15530 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
15540 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
15550 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
15560 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
15570 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
15580 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
15590 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
155a0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
155b0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
155c0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
155d0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
155e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
155f0 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
15600 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
15610 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
15620 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a  null-terminated.
15630 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
15640 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
15650 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
15660 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
15670 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
15680 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
15690 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
156a0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
156b0 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
156c0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
156d0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
156e0 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
156f0 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
15700 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
15710 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
15720 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
15730 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
15740 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
15750 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
15760 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
15770 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
15780 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
15790 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
157a0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
157b0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
157c0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
157d0 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
157e0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
157f0 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
15800 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
15810 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
15820 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
15830 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
15840 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
15850 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
15860 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
15870 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
15880 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
15890 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
158a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
158b0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
158c0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
158d0 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
158e0 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
158f0 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
15900 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
15910 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
15920 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
15930 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
15940 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
15950 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
15960 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
15970 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
15980 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
15990 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
159a0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
159b0 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
159c0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
159d0 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
159e0 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
159f0 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
15a00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
15a10 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
15a20 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
15a30 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
15a40 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
15a50 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
15a60 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
15a70 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
15a80 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
15a90 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
15aa0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
15ab0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
15ac0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
15ad0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
15ae0 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
15af0 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
15b00 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
15b10 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
15b20 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
15b30 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
15b40 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
15b50 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
15b60 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
15b70 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
15b80 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
15b90 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
15ba0 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
15bb0 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
15bc0 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
15bd0 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
15be0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
15bf0 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
15c00 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
15c10 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
15c20 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
15c30 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
15c40 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
15c50 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
15c60 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
15c70 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
15c80 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
15c90 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
15ca0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
15cb0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
15cc0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
15cd0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
15ce0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
15cf0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
15d00 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
15d10 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
15d20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
15d30 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
15d40 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
15d50 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
15d60 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
15d70 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
15d80 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
15d90 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
15da0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
15db0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
15dc0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
15dd0 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
15de0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
15df0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
15e00 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
15e10 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
15e20 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
15e30 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
15e40 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
15e50 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
15e60 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
15e70 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
15e80 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
15e90 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
15ea0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
15eb0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
15ec0 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
15ed0 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
15ee0 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
15ef0 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
15f00 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
15f10 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
15f20 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
15f30 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
15f40 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
15f50 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
15f60 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
15f70 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
15f80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
15f90 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
15fa0 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
15fb0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
15fc0 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
15fd0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
15fe0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
15ff0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
16000 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
16010 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
16020 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
16030 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
16040 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
16050 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
16060 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
16070 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
16080 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
16090 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
160a0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
160b0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
160c0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
160d0 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
160e0 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
160f0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
16100 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
16110 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
16120 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
16130 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
16140 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
16150 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
16160 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
16170 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
16180 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
16190 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
161a0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
161b0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
161c0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
161d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
161e0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
161f0 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
16200 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
16210 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
16220 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
16230 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
16240 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
16250 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
16260 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
16270 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
16280 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
16290 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
162a0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
162b0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
162c0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
162d0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
162e0 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
162f0 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
16300 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
16310 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
16320 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
16330 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
16340 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
16350 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
16360 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
16370 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
16380 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
16390 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
163a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
163b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
163c0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lloc()..**.** ^(
163d0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
163e0 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
163f0 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
16400 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
16410 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
16420 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
16430 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
16440 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
16450 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
16460 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16470 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
16480 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
16490 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20   parameter.)^ ^ 
164a0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
164b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
164c0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
164d0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
164e0 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
164f0 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
16500 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
16510 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
16520 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
16530 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16540 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
16550 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  oc()..** ^If the
16560 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16570 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
16580 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
16590 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
165a0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
165b0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
165c0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
165d0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
165e0 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
165f0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16600 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
16610 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  loc()..** ^sqlit
16620 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
16630 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
16640 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
16650 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
16660 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
16670 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
16680 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
16690 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
166a0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
166b0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
166c0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
166d0 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
166e0 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
166f0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
16700 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
16710 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
16720 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
16730 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
16740 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
16750 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
16760 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
16770 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
16780 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
16790 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
167a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
167b0 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
167c0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
167d0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
167e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
167f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
16800 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
16810 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
16820 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
16830 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  ndary..**.** In 
16840 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
16850 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
16860 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
16870 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
16880 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
16890 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
168a0 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
168b0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
168c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
168d0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
168e0 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
168f0 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
16900 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
16910 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
16920 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
16930 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
16940 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
16950 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  The Windows OS i
16960 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
16970 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74  alls.** the syst
16980 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
16990 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
169a0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
169b0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
169c0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
169d0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
169e0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
169f0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
16a00 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
16a10 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
16a20 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
16a30 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
16a40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
16a50 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74  rrors are detect
16a60 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
16a70 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  are reported bac
16a80 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
16a90 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
16aa0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
16ab0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
16ac0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
16ad0 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
16ae0 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
16af0 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
16b00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
16b10 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
16b20 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
16b30 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
16b40 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
16b50 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
16b60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16b70 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
16b80 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
16b90 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
16ba0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
16bb0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
16bc0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
16bd0 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
16be0 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
16bf0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
16c00 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
16c10 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
16c20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
16c30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
16c40 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
16c50 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
16c60 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
16c70 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
16c80 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
16c90 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
16ca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16cb0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
16cc0 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
16cd0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
16ce0 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
16cf0 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
16d00 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
16d10 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
16d20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16d30 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
16d40 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
16d50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
16d60 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
16d70 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
16d80 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
16d90 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
16da0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
16db0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
16dc0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
16dd0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
16de0 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
16df0 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
16e00 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
16e10 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
16e20 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
16e30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
16e40 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
16e50 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
16e60 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
16e70 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
16e80 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
16e90 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
16ea0 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
16eb0 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
16ec0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
16ed0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
16ee0 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
16ef0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
16f00 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
16f10 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
16f20 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
16f30 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
16f40 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
16f50 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
16f60 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
16f70 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
16f80 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
16f90 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
16fa0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
16fb0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16fc0 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
16fd0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
16fe0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
16ff0 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
17000 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
17010 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
17020 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
17030 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
17040 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
17050 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
17060 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
17070 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
17080 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
17090 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
170a0 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
170b0 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
170c0 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
170d0 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
170e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
170f0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
17100 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
17110 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
17120 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
17130 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
17140 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17150 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
17160 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
17170 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
17180 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
17190 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
171a0 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
171b0 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
171c0 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
171d0 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
171e0 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
171f0 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
17200 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
17210 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
17220 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
17230 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
17240 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
17250 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
17260 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
17270 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
17280 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
17290 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
172a0 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
172b0 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
172c0 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
172d0 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
172e0 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
172f0 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
17300 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
17310 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
17320 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
17330 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
17340 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
17350 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
17360 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
17370 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
17380 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
17390 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
173a0 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
173b0 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
173c0 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
173d0 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
173e0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
173f0 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
17400 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  On all subsequen
17410 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74  t invocations, t
17420 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
17430 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
17440 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
17450 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
17460 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
17470 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
17480 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
17490 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
174a0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
174b0 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
174c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
174d0 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
174e0 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
174f0 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ks.**.** ^This r
17500 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
17510 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   a authorizer ca
17520 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
17530 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
17540 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17550 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
17560 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17570 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
17580 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
17590 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
175a0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
175b0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
175c0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
175d0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
175e0 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
175f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
17600 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
17610 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
17620 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
17630 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
17640 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
17650 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
17660 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
17670 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
17680 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
17690 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
176a0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
176b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
176c0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
176d0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
176e0 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
176f0 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
17700 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
17710 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
17720 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
17730 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
17740 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
17750 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
17760 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
17770 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
17780 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
17790 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
177a0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
177b0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
177c0 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
177d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
177e0 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
177f0 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
17800 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
17810 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
17820 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
17830 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
17840 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
17850 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
17860 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
17870 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
17880 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
17890 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
178a0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
178b0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
178c0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
178d0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
178e0 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
178f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
17900 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
17910 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
17920 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
17930 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
17940 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
17950 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
17960 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
17970 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17980 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
17990 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
179a0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
179b0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
179c0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
179d0 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
179e0 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
179f0 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
17a00 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
17a10 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
17a20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17a30 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
17a40 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
17a50 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
17a60 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
17a70 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
17a80 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
17a90 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
17aa0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
17ab0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
17ac0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
17ad0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
17ae0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
17af0 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
17b00 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
17b10 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
17b20 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
17b30 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
17b40 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
17b50 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
17b60 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
17b70 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
17b80 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
17b90 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
17ba0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
17bb0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
17bc0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
17bd0 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
17be0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
17bf0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
17c00 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
17c10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
17c20 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
17c30 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
17c40 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
17c50 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
17c60 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
17c70 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
17c80 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
17c90 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
17ca0 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
17cb0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
17cc0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
17cd0 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
17ce0 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
17cf0 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
17d00 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
17d10 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
17d20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
17d30 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
17d40 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
17d50 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
17d60 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
17d70 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
17d80 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
17d90 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
17da0 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
17db0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
17dc0 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
17dd0 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
17de0 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
17df0 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
17e00 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
17e10 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
17e20 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
17e30 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
17e40 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
17e50 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
17e60 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
17e70 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
17e80 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
17e90 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
17ea0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
17eb0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
17ec0 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
17ed0 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
17ee0 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
17ef0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
17f00 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
17f10 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
17f20 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
17f30 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
17f40 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
17f50 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
17f60 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
17f70 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
17f80 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
17f90 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
17fa0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
17fb0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
17fc0 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
17fd0 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
17fe0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
17ff0 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
18000 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
18010 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
18020 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
18030 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
18040 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18050 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
18060 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
18070 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
18080 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
18090 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
180a0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
180b0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
180c0 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
180d0 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
180e0 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
180f0 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
18100 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
18110 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
18120 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
18130 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
18140 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
18150 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
18160 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
18170 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
18180 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
18190 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
181a0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
181b0 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
181c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
181d0 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
181e0 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
181f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
18200 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
18210 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
18220 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
18230 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
18240 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
18250 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
18260 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
18270 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
18280 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
18290 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
182a0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
182b0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
182c0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
182d0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
182e0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
182f0 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
18300 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
18310 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
18320 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
18330 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
18340 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
18350 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
18360 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18370 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
18380 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
18390 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
183a0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
183b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
183c0 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
183d0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
183e0 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
183f0 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
18400 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
18410 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
18420 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
18430 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
18440 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
18450 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
18460 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
18470 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
18480 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
18490 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
184a0 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
184b0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
184c0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
184d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
184e0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
184f0 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
18500 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
18510 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
18520 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
18530 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
18540 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
18550 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
18560 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
18570 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
18580 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
18590 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
185a0 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
185b0 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
185c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
185d0 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
185e0 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
185f0 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
18600 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nge..*/.int sqli
18610 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
18620 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
18630 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
18640 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
18650 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
18660 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
18670 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
18680 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
18690 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
186a0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
186b0 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
186c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
186d0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
186e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
186f0 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
18700 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
18710 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
18720 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
18730 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
18740 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
18750 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
18760 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
18770 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
18780 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
18790 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
187a0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
187b0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
187c0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
187d0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
187e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
187f0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
18800 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
18810 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
18820 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
18830 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
18840 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
18850 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
18860 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
18870 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
18880 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
18890 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
188a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
188b0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
188c0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
188d0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
188e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
188f0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
18900 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
18910 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
18920 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
18930 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
18940 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
18950 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
18960 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
18970 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
18980 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
18990 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
189a0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
189b0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
189c0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
189d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
189e0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
189f0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
18a00 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
18a10 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
18a20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
18a30 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
18a40 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
18a50 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
18a60 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
18a70 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
18a80 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
18a90 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
18aa0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
18ab0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
18ac0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
18ad0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
18ae0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
18af0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
18b00 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
18b10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
18b20 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
18b30 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
18b40 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
18b50 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
18b60 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
18b70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
18b80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18b90 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
18ba0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
18bb0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
18bc0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
18bd0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
18be0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
18bf0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
18c00 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
18c10 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
18c20 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
18c30 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
18c40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18c50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18c60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
18c70 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
18c80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
18c90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18ca0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
18cb0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
18cc0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
18cd0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
18ce0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18cf0 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
18d00 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
18d10 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18d20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18d30 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18d40 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
18d50 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
18d60 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
18d70 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
18d80 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18d90 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
18da0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
18db0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18dc0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18dd0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
18de0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
18df0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
18e00 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
18e10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18e20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
18e30 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
18e40 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
18e50 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18e60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18e70 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
18e80 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
18e90 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
18ea0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
18eb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18ec0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
18ed0 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
18ee0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
18ef0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18f00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18f10 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
18f20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
18f30 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18f40 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18f50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18f60 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
18f70 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
18f80 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
18f90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18fa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18fb0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
18fc0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
18fd0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18fe0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18ff0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19000 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
19010 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
19020 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
19030 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19040 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19050 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
19060 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
19070 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
19080 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
19090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
190a0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
190b0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
190c0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
190d0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
190e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
190f0 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
19100 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
19110 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
19120 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19130 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
19140 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
19150 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
19160 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
19170 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
19180 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
19190 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
191a0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
191b0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
191c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
191d0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
191e0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
191f0 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
19200 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
19210 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19220 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
19230 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
19240 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
19250 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
19260 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
19270 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
19280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
19290 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
192a0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
192b0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
192c0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
192d0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
192e0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
192f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19300 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19310 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
19320 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
19330 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
19340 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19350 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19360 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
19370 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
19380 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
19390 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
193a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
193b0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
193c0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
193d0 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
193e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
193f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19400 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
19410 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
19420 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
19430 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19440 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19450 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
19460 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
19470 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
19480 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19490 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
194a0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
194b0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
194c0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
194d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
194e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
194f0 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
19500 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
19510 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
19520 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19530 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19540 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
19550 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
19560 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
19570 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
19580 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19590 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
195a0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
195b0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
195c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
195d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
195e0 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
195f0 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
19600 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
19610 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
19620 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
19630 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
19640 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
19650 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
19660 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
19670 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
19680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19690 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
196a0 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
196b0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
196c0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
196d0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
196e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
196f0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
19700 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
19710 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
19720 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
19730 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
19740 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
19750 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
19760 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
19770 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
19780 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
19790 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
197a0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
197b0 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
197c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
197d0 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
197e0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
197f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
19800 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
19810 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
19820 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
19830 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
19840 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
19850 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
19860 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
19870 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
19880 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
19890 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
198a0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
198b0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
198c0 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
198d0 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
198e0 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
198f0 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
19900 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
19910 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
19920 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
19930 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )^.**.** ^The ca
19940 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
19950 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
19960 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
19970 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
19980 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
19990 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
199a0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
199b0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
199c0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
199d0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
199e0 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
199f0 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
19a00 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
19a10 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
19a20 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2f 0a 76 6f  ok to run..*/.vo
19a30 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
19a40 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
19a50 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
19a60 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
19a70 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50  id*);.SQLITE_EXP
19a80 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
19a90 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
19aa0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
19ab0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
19ac0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
19ad0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
19ae0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
19af0 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
19b00 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
19b10 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
19b20 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73  utine configures
19b30 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
19b40 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72  tion - the.** pr
19b50 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
19b60 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  - that is invoke
19b70 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
19b80 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75  uring long.** ru
19b90 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  nning calls to [
19ba0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
19bb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19bc0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
19bd0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20  3_get_table()]. 
19be0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
19bf0 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
19c00 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
19c10 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
19c20 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
19c30 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ery..**.** ^If t
19c40 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
19c50 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
19c60 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
19c70 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
19c80 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
19c90 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
19ca0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
19cb0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
19cc0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
19cd0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
19ce0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
19cf0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73  ress handler mus
19d00 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
19d10 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
19d20 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
19d30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
19d40 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
19d50 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
19d60 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
19d70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
19d80 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
19d90 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
19da0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
19db0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19dc0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
19dd0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
19de0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
19df0 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
19e00 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
19e10 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
19e20 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
19e30 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
19e40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
19e50 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
19e60 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
19e70 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
19e80 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
19e90 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
19ea0 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73  le whose name is
19eb0 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a   given by the.**
19ec0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
19ed0 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
19ee0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
19ef0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
19f00 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
19f10 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
19f20 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
19f30 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
19f40 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
19f50 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
19f60 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
19f70 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
19f80 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
19f90 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
19fa0 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
19fb0 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
19fc0 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
19fd0 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
19fe0 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
19ff0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
1a000 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
1a010 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
1a020 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
1a030 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
1a040 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
1a050 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
1a060 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1a070 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
1a080 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
1a090 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1a0a0 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
1a0b0 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
1a0c0 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
1a0d0 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
1a0e0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
1a0f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1a100 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
1a110 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1a120 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
1a130 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
1a140 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
1a150 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
1a160 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
1a170 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
1a180 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
1a190 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
1a1a0 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
1a1b0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
1a1c0 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
1a1d0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
1a1e0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
1a1f0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1a200 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
1a210 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1a220 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1a230 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
1a240 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
1a250 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1a260 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
1a270 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
1a280 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
1a290 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
1a2a0 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
1a2b0 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
1a2c0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1a2d0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1a2e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1a2f0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
1a300 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
1a310 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
1a320 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
1a330 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
1a340 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
1a350 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
1a360 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
1a370 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
1a380 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
1a390 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1a3a0 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
1a3b0 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
1a3c0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
1a3d0 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
1a3e0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1a3f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
1a400 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
1a410 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
1a420 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
1a430 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
1a440 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
1a450 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
1a460 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
1a470 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
1a480 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1a490 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1a4a0 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
1a4b0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1a4c0 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ACHE],.** and/or
1a4d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
1a4e0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
1a4f0 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
1a500 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1a510 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
1a520 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1a530 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1a540 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
1a550 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
1a560 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
1a570 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
1a580 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
1a590 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1a5a0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1a5b0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1a5c0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1a5d0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1a5e0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1a5f0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
1a600 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
1a610 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
1a620 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
1a630 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
1a640 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1a650 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
1a660 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
1a670 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
1a680 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
1a690 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
1a6a0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
1a6b0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
1a6c0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1a6d0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
1a6e0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
1a6f0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1a700 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1a710 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1a720 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
1a730 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20  reates it if.** 
1a740 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
1a750 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
1a760 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
1a770 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
1a780 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
1a790 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1a7a0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
1a7b0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
1a7c0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
1a7d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1a7e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1a7f0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
1a800 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
1a810 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72  s shown above or
1a820 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62   one of the comb
1a830 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1a840 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a  bove combined.**
1a850 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
1a860 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
1a870 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1a880 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51  LLMUTEX],.** [SQ
1a890 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1a8a0 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53  CACHE] and/or [S
1a8b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1a8c0 44 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a  DCACHE] flags,.*
1a8d0 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1a8e0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1a8f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1a900 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1a910 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1a920 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1a930 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1a940 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1a950 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1a960 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1a970 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1a980 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1a990 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1a9a0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1a9b0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1a9c0 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1a9d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1a9e0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1a9f0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1aa00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1aa10 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1aa20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1aa30 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1aa40 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1aa50 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1aa60 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1aa70 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1aa80 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1aa90 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1aaa0 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1aab0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1aac0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1aad0 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1aae0 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1aaf0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1ab00 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1ab10 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1ab20 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1ab30 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1ab40 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1ab50 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1ab60 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1ab70 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1ab80 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1ab90 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1aba0 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1abb0 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1abc0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1abd0 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1abe0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1abf0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
1ac00 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1ac10 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1ac20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
1ac30 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
1ac40 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1ac50 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
1ac60 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
1ac70 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
1ac80 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
1ac90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1aca0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
1acb0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1acc0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1acd0 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
1ace0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
1acf0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
1ad00 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
1ad10 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
1ad20 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
1ad30 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
1ad40 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
1ad50 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
1ad60 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
1ad70 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
1ad80 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
1ad90 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
1ada0 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
1adb0 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
1adc0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
1add0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1ade0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
1adf0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
1ae00 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1ae10 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
1ae20 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
1ae30 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
1ae40 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
1ae50 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
1ae60 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
1ae70 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
1ae80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1ae90 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1aea0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
1aeb0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1aec0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1aed0 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1aee0 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1aef0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1af00 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1af10 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1af20 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1af30 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1af40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1af50 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
1af60 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1af70 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1af80 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1af90 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1afa0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1afb0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
1afc0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1afd0 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1afe0 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1aff0 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1b000 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1b010 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1b020 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1b030 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1b040 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1b050 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1b060 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1b070 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1b080 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1b090 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1b0a0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1b0b0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1b0c0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1b0d0 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1b0e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1b0f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1b100 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
1b110 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
1b120 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1b130 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1b140 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1b150 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1b160 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1b170 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1b180 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1b190 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
1b1a0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
1b1b0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1b1c0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1b1d0 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
1b1e0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1b1f0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1b200 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1b210 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1b220 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1b230 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1b240 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1b250 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1b260 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1b270 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1b280 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1b290 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1b2a0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1b2b0 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1b2c0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1b2d0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1b2e0 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1b2f0 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1b300 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1b310 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1b320 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
1b330 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1b340 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1b350 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
1b360 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1b370 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1b380 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1b390 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
1b3a0 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
1b3b0 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
1b3c0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
1b3d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b3e0 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
1b3f0 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
1b400 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
1b410 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1b420 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1b430 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1b440 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
1b450 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
1b460 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1b470 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1b480 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
1b490 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
1b4a0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
1b4b0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1b4c0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1b4d0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
1b4e0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
1b4f0 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
1b500 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
1b510 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1b520 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1b530 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1b540 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1b550 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1b560 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1b570 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1b580 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1b590 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1b5a0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
1b5b0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1b5c0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1b5d0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1b5e0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1b5f0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1b600 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1b610 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1b620 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1b630 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1b640 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1b650 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1b660 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1b670 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1b680 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1b690 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1b6a0 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68  ions.)^.**.** Wh
1b6b0 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
1b6c0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1b6d0 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
1b6e0 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
1b6f0 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
1b700 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
1b710 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
1b720 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
1b730 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
1b740 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
1b750 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
1b760 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
1b770 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
1b780 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
1b790 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
1b7a0 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
1b7b0 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
1b7c0 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
1b7d0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1b7e0 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
1b7f0 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
1b800 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
1b810 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
1b820 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1b830 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1b840 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
1b850 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
1b860 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
1b870 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
1b880 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
1b890 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
1b8a0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1b8b0 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
1b8c0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1b8d0 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
1b8e0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
1b8f0 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
1b900 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
1b910 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
1b920 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
1b930 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
1b940 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
1b950 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
1b960 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
1b970 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
1b980 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
1b990 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
1b9a0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
1b9b0 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
1b9c0 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
1b9d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1b9e0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1b9f0 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
1ba00 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1ba10 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1ba20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1ba30 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
1ba40 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
1ba50 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1ba60 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
1ba70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1ba80 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
1ba90 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
1baa0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1bab0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
1bac0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
1bad0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
1bae0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
1baf0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
1bb00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1bb10 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
1bb20 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
1bb30 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
1bb40 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
1bb50 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
1bb60 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
1bb70 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
1bb80 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
1bb90 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
1bba0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
1bbb0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
1bbc0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
1bbd0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
1bbe0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
1bbf0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1bc00 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
1bc10 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
1bc20 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
1bc30 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
1bc40 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
1bc50 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
1bc60 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
1bc70 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
1bc80 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
1bc90 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
1bca0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bcb0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1bcc0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
1bcd0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
1bce0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
1bcf0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
1bd00 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
1bd10 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
1bd20 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
1bd30 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
1bd40 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
1bd50 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1bd60 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
1bd70 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
1bd80 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
1bd90 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
1bda0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
1bdb0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1bdc0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1bdd0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1bde0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
1bdf0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
1be00 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
1be10 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
1be20 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
1be30 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
1be40 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
1be50 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
1be60 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
1be70 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
1be80 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
1be90 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1bea0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
1beb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bec0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
1bed0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
1bee0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
1bef0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1bf00 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
1bf10 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1bf20 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
1bf30 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
1bf40 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
1bf50 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
1bf60 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
1bf70 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
1bf80 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
1bf90 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e  struct.  The fun
1bfa0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1bfb0 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a  e old limit.)^.*
1bfc0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
1bfd0 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
1bfe0 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
1bff0 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
1c000 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68  ged..** ^(For th
1c010 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  e limit category
1c020 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54   of SQLITE_LIMIT
1c030 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20  _XYZ there is a 
1c040 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
1c050 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
1c060 2a 2a 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70  ** set by a comp
1c070 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72  ile-time C prepr
1c080 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61  ocessor macro na
1c090 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  med .** [limits 
1c0a0 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a  | SQLITE_MAX_XYZ
1c0b0 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
1c0c0 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1c0d0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1c0e0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
1c0f0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1c100 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1c110 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1c120 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1c130 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1c140 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1c150 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
1c160 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
1c170 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
1c180 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
1c190 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
1c1a0 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
1c1b0 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
1c1c0 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
1c1d0 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
1c1e0 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
1c1f0 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
1c200 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
1c210 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
1c220 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
1c230 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
1c240 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
1c250 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
1c260 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
1c270 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
1c280 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
1c290 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
1c2a0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
1c2b0 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
1c2c0 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
1c2d0 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
1c2e0 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
1c2f0 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
1c300 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
1c310 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
1c320 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
1c330 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
1c340 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
1c350 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
1c360 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
1c370 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
1c380 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
1c390 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
1c3a0 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
1c3b0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
1c3c0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1c3d0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
1c3e0 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
1c3f0 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
1c400 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
1c410 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
1c420 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
1c430 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
1c440 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
1c450 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
1c460 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1c470 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
1c480 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
1c490 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
1c4a0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
1c4b0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
1c4c0 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
1c4d0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
1c4e0 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
1c4f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c500 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
1c510 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
1c520 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
1c530 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
1c540 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
1c550 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
1c560 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
1c570 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
1c580 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
1c590 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
1c5a0 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
1c5b0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
1c5c0 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
1c5d0 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
1c5e0 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
1c5f0 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
1c600 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
1c610 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
1c620 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
1c630 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
1c640 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
1c650 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
1c660 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
1c670 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1c680 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
1c690 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
1c6a0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
1c6b0 20 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a   row.<dd>)^.**.*
1c6c0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1c6d0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
1c6e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c6f0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1c700 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
1c710 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
1c720 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1c730 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1c740 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
1c750 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c760 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1c770 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
1c780 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
1c790 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
1c7a0 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
1c7b0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1c7c0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1c7d0 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
1c7e0 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
1c7f0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
1c800 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1c810 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1c820 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
1c830 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1c840 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
1c850 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
1c860 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
1c870 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1c880 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
1c890 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
1c8a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c8b0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1c8c0 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
1c8d0 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
1c8e0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
1c8f0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1c900 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
1c910 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c920 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1c930 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
1c940 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
1c950 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
1c960 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1c970 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1c980 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1c990 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1c9a0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
1c9b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c9c0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1c9d0 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
1c9e0 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
1c9f0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1ca00 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1ca10 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
1ca20 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1ca30 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
1ca40 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1ca50 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
1ca60 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1ca70 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1ca80 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1ca90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1caa0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
1cab0 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
1cac0 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
1cad0 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
1cae0 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
1caf0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1cb00 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1cb10 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
1cb20 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1cb30 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73  ber of variables
1cb40 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1cb50 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a  ment that can.**
1cb60 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29   be bound.</dd>)
1cb70 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1cb80 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
1cb90 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
1cba0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1cbb0 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
1cbc0 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
1cbd0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
1cbe0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
1cbf0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1cc00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1cc10 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
1cc20 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1cc30 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1cc40 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
1cc50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1cc60 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
1cc70 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
1cc80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
1cc90 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1cca0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
1ccb0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1ccc0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
1ccd0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
1cce0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
1ccf0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
1cd00 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
1cd10 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1cd20 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
1cd30 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
1cd40 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1cd50 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
1cd60 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
1cd70 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1cd80 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1cd90 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
1cda0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1cdb0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1cdc0 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
1cdd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1cde0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
1cdf0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
1ce00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ce10 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
1ce20 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
1ce30 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
1ce40 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
1ce50 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
1ce60 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
1ce70 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
1ce80 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
1ce90 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
1cea0 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
1ceb0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1cec0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
1ced0 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
1cee0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
1cef0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
1cf00 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
1cf10 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
1cf20 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1cf30 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1cf40 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1cf50 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1cf60 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
1cf70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cf80 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
1cf90 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
1cfa0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
1cfb0 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
1cfc0 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
1cfd0 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
1cfe0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
1cff0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1d000 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
1d010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1d020 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1d030 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
1d040 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
1d050 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
1d060 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
1d070 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1d080 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
1d090 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
1d0a0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1d0b0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
1d0c0 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
1d0d0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
1d0e0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
1d0f0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
1d100 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1d110 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
1d120 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
1d130 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
1d140 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
1d150 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
1d160 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1d170 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
1d180 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
1d190 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
1d1a0 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
1d1b0 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
1d1c0 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
1d1d0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
1d1e0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
1d1f0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
1d200 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
1d210 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
1d220 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
1d230 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
1d240 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
1d250 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
1d260 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
1d270 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
1d280 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
1d290 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
1d2a0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
1d2b0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
1d2c0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
1d2d0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
1d2e0 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a  inator bytes..**
1d2f0 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
1d300 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
1d310 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
1d320 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
1d330 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
1d340 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1d350 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1d360 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
1d370 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1d380 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
1d390 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
1d3a0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
1d3b0 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
1d3c0 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
1d3d0 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
1d3e0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
1d3f0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
1d400 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
1d410 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
1d420 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
1d430 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
1d440 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1d450 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
1d460 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
1d470 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
1d480 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
1d490 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
1d4a0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
1d4b0 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
1d4c0 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
1d4d0 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
1d4e0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
1d4f0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
1d500 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
1d510 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
1d520 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
1d530 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
1d540 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
1d550 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1d560 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
1d570 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
1d580 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
1d590 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
1d5a0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
1d5b0 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
1d5c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1d5d0 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
1d5e0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
1d5f0 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
1d600 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1d610 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1d620 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1d630 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d640 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1d650 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
1d660 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
1d670 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
1d680 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
1d690 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
1d6a0 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
1d6b0 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
1d6c0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1d6d0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
1d6e0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
1d6f0 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
1d700 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
1d710 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1d720 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
1d730 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
1d740 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1d750 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
1d760 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
1d770 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
1d780 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
1d790 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1d7a0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
1d7b0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
1d7c0 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
1d7d0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
1d7e0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
1d7f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
1d800 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
1d810 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
1d820 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
1d830 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
1d840 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
1d850 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1d860 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
1d870 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
1d880 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
1d890 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
1d8a0 20 69 74 20 61 67 61 69 6e 2e 20 20 5e 49 66 20   it again.  ^If 
1d8b0 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
1d8c0 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77  hanged in.** a w
1d8d0 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ay that makes th
1d8e0 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
1d8f0 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
1d900 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1d910 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
1d920 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
1d930 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
1d940 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
1d950 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  ior, [SQLITE_SCH
1d960 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61  EMA] is.** now a
1d970 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
1d980 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1d990 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
1d9a0 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
1d9b0 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
1d9c0 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
1d9d0 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
1d9e0 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
1d9f0 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
1da00 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
1da10 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
1da20 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
1da30 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c  ] return..** </l
1da40 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1da50 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
1da60 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
1da70 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
1da80 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
1da90 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
1daa0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
1dab0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
1dac0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
1dad0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
1dae0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
1daf0 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
1db00 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
1db10 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
1db20 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
1db30 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
1db40 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
1db50 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
1db60 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
1db70 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
1db80 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
1db90 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
1dba0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
1dbb0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
1dbc0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
1dbd0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
1dbe0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
1dbf0 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
1dc00 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1dc10 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1dc20 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
1dc30 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61  f the value of a
1dc40 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
1dc50 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
1dc60 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
1dc70 65 20 6d 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67  e might.** chang
1dc80 65 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e  e the query plan
1dc90 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
1dca0 2c 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  , then the state
1dcb0 6d 65 6e 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61  ment may be.** a
1dcc0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
1dcd0 6f 6d 70 69 6c 65 64 20 28 61 73 20 69 66 20 74  ompiled (as if t
1dce0 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 61 20  here had been a 
1dcf0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 29 20 6f  schema change) o
1dd00 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20  n the first .** 
1dd10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1dd20 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
1dd30 61 6e 79 20 63 68 61 6e 67 65 20 74 6f 20 74 68  any change to th
1dd40 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  e .** [sqlite3_b
1dd50 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
1dd60 6e 67 73 5d 20 6f 66 20 74 68 65 20 5b 70 61 72  ngs] of the [par
1dd70 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c  ameter]. .** </l
1dd80 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
1dd90 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1dda0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
1ddb0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1ddc0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1ddd0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1dde0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1ddf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1de00 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1de10 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1de20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1de30 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1de40 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1de50 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1de60 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1de70 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1de80 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1de90 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1dea0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1deb0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1dec0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1ded0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1dee0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
1def0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1df00 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1df10 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1df20 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1df30 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1df40 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1df50 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1df60 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1df70 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1df80 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1df90 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1dfa0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1dfb0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1dfc0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1dfd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1dfe0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1dff0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1e000 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1e010 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1e020 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
1e030 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1e040 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1e050 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1e060 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
1e070 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1e080 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
1e090 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
1e0a0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1e0b0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1e0c0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1e0d0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1e0e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1e0f0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1e100 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1e110 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1e120 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1e130 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1e140 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1e150 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1e160 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1e170 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
1e180 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1e190 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1e1a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1e1b0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
1e1c0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1e1d0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
1e1e0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1e1f0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1e200 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1e210 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1e220 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1e230 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1e240 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1e250 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1e260 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
1e270 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1e280 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1e290 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1e2a0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1e2b0 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
1e2c0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
1e2d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
1e2e0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
1e2f0 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
1e300 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
1e310 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
1e320 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
1e330 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
1e340 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
1e350 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1e360 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
1e370 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
1e380 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e390 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1e3a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1e3b0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1e3c0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1e3d0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1e3e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1e3f0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
1e400 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1e410 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
1e420 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1e430 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
1e440 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1e450 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
1e460 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
1e470 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1e480 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
1e490 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
1e4a0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
1e4b0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1e4c0 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
1e4d0 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
1e4e0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
1e4f0 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
1e500 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
1e510 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e520 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
1e530 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
1e540 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
1e550 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
1e560 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
1e570 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1e580 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
1e590 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
1e5a0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
1e5b0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
1e5c0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
1e5d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e5e0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
1e5f0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
1e600 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
1e610 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
1e620 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
1e630 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
1e640 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
1e650 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
1e660 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
1e670 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
1e680 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
1e690 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
1e6a0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e6b0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
1e6c0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
1e6d0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
1e6e0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
1e6f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
1e700 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
1e710 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
1e720 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1e730 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
1e740 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e750 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
1e760 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
1e770 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1e780 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e790 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
1e7a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
1e7b0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
1e7c0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
1e7d0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
1e7e0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
1e7f0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
1e800 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
1e810 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
1e820 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
1e830 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
1e840 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
1e850 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1e860 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
1e870 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
1e880 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
1e890 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
1e8a0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
1e8b0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
1e8c0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1e8d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
1e8e0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
1e8f0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
1e900 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
1e910 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
1e920 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
1e930 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1e940 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
1e950 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
1e960 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
1e970 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
1e980 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1e990 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1e9a0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e9b0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
1e9c0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
1e9d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1e9e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e9f0 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
1ea00 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
1ea10 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
1ea20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1ea30 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
1ea40 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1ea50 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
1ea60 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
1ea70 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1ea80 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1ea90 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1eaa0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
1eab0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
1eac0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1ead0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
1eae0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
1eaf0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
1eb00 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
1eb10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
1eb20 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
1eb30 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
1eb40 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
1eb50 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
1eb60 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
1eb70 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
1eb80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1eb90 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
1eba0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1ebb0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
1ebc0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
1ebd0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
1ebe0 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
1ebf0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
1ec00 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
1ec10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
1ec20 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
1ec30 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
1ec40 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
1ec50 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
1ec60 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
1ec70 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
1ec80 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
1ec90 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
1eca0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1ecb0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
1ecc0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1ecd0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
1ece0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
1ecf0 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
1ed00 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
1ed10 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
1ed20 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
1ed30 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
1ed40 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
1ed50 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
1ed60 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
1ed70 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
1ed80 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
1ed90 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
1eda0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
1edb0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
1edc0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
1edd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
1ede0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
1edf0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1ee00 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
1ee10 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
1ee20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
1ee30 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
1ee40 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
1ee50 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
1ee60 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
1ee70 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
1ee80 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
1ee90 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
1eea0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
1eeb0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
1eec0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
1eed0 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
1eee0 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
1eef0 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
1ef00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
1ef10 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
1ef20 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
1ef30 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
1ef40 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
1ef50 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
1ef60 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
1ef70 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
1ef80 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
1ef90 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
1efa0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
1efb0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
1efc0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
1efd0 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
1efe0 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
1eff0 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
1f000 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
1f010 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
1f020 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
1f030 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
1f040 69 63 20 69 64 65 6e 74 69 66 65 72 2e 29 5e 20  ic identifer.)^ 
1f050 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
1f060 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
1f070 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
1f080 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
1f090 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
1f0a0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
1f0b0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
1f0c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1f0d0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
1f0e0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
1f0f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1f100 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
1f110 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1f120 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
1f130 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
1f140 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
1f150 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
1f160 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
1f170 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1f180 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1f190 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1f1a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1f1b0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
1f1c0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
1f1d0 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
1f1e0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
1f1f0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
1f200 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
1f210 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
1f220 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
1f230 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
1f240 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
1f250 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
1f260 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
1f270 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
1f280 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
1f290 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
1f2a0 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
1f2b0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
1f2c0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
1f2d0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
1f2e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1f2f0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1f300 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
1f310 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
1f320 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
1f330 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
1f340 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
1f350 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
1f360 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
1f370 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
1f380 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
1f390 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
1f3a0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1f3b0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
1f3c0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
1f3d0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
1f3e0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
1f3f0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
1f400 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
1f410 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
1f420 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
1f430 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
1f440 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
1f450 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
1f460 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
1f470 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
1f480 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
1f490 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
1f4a0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
1f4b0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
1f4c0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
1f4d0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
1f4e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
1f4f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
1f500 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65  negative, the le
1f510 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
1f520 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
1f530 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
1f540 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
1f550 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
1f560 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
1f570 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1f580 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
1f590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1f5a0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
1f5b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
1f5c0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
1f5d0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
1f5e0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
1f5f0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
1f600 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
1f610 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 5e 49  shed with it. ^I
1f620 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
1f630 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
1f640 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
1f650 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
1f660 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
1f670 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
1f680 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
1f690 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
1f6a0 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
1f6b0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
1f6c0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
1f6d0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1f6e0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
1f6f0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
1f700 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
1f710 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
1f720 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1f730 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
1f740 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
1f750 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1f760 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
1f770 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
1f780 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
1f790 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
1f7a0 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
1f7b0 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
1f7c0 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
1f7d0 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
1f7e0 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
1f7f0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
1f800 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
1f810 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
1f820 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
1f830 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
1f840 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
1f850 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
1f860 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
1f870 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
1f880 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
1f890 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
1f8a0 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
1f8b0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
1f8c0 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
1f8d0 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
1f8e0 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
1f8f0 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
1f900 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
1f910 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
1f920 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
1f930 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
1f940 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1f950 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
1f960 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1f970 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
1f980 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1f990 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
1f9a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1f9b0 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
1f9c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f9d0 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
1f9e0 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
1f9f0 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
1fa00 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
1fa10 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
1fa20 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
1fa30 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
1fa40 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
1fa50 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
1fa60 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
1fa70 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
1fa80 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
1fa90 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
1faa0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
1fab0 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
1fac0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
1fad0 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
1fae0 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
1faf0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
1fb00 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
1fb10 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
1fb20 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1fb30 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
1fb40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
1fb50 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1fb60 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
1fb70 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
1fb80 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
1fb90 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
1fba0 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
1fbb0 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
1fbc0 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
1fbd0 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
1fbe0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
1fbf0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
1fc00 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
1fc10 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
1fc20 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1fc30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1fc40 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
1fc50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1fc60 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1fc70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1fc80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1fc90 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
1fca0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
1fcb0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1fcc0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
1fcd0 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
1fce0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1fcf0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
1fd00 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
1fd10 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
1fd20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1fd30 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
1fd40 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
1fd50 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1fd60 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
1fd70 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
1fd80 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
1fd90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
1fda0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
1fdb0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
1fdc0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
1fdd0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1fde0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
1fdf0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
1fe00 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
1fe10 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
1fe20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1fe30 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1fe40 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
1fe50 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1fe60 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
1fe70 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1fe80 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
1fe90 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
1fea0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1feb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1fec0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
1fed0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1fee0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
1fef0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
1ff00 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
1ff10 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
1ff20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
1ff30 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
1ff40 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
1ff50 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
1ff60 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1ff70 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
1ff80 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
1ff90 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
1ffa0 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
1ffb0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
1ffc0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
1ffd0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
1ffe0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1fff0 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
20000 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
20010 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
20020 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
20030 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
20040 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
20050 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
20060 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
20070 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
20080 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
20090 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
200a0 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
200b0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
200c0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
200d0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
200e0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
200f0 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
20100 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
20110 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
20120 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
20130 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
20140 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
20150 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
20160 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
20170 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
20180 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
20190 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
201a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
201b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
201c0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
201d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
201e0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
201f0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
20200 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
20210 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20220 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
20230 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
20240 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
20250 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
20260 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
20270 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20280 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
20290 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
202a0 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
202b0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
202c0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
202d0 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
202e0 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
202f0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
20300 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
20310 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
20320 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
20330 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
20340 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
20350 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
20360 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
20370 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
20380 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
20390 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
203a0 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
203b0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
203c0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
203d0 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
203e0 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
203f0 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
20400 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
20410 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
20420 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
20430 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
20440 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
20450 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
20460 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
20470 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
20480 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
20490 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
204a0 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
204b0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
204c0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
204d0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
204e0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
204f0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
20500 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
20510 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
20520 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
20530 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
20540 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
20550 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
20560 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
20570 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
20580 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
20590 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
205a0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
205b0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
205c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
205d0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
205e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
205f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
20600 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
20610 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
20620 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
20630 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
20640 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
20650 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
20660 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
20670 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
20680 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
20690 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
206a0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
206b0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
206c0 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
206d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
206e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
206f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
20700 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
20710 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
20720 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
20730 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
20740 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
20750 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
20760 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
20770 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
20780 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
20790 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
207a0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
207b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
207c0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
207d0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
207e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
207f0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
20800 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
20810 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
20820 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
20830 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
20840 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
20850 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
20860 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
20870 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
20880 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
20890 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
208a0 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
208b0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
208c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
208d0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
208e0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
208f0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
20900 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
20910 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
20920 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
20930 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
20940 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
20950 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
20960 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
20970 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
20980 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
20990 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
209a0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
209b0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
209c0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
209d0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
209e0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
209f0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
20a00 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
20a10 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
20a20 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
20a30 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
20a40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20a50 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
20a60 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
20a70 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
20a80 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
20a90 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
20aa0 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
20ab0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
20ac0 5d 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ])..*/.int sqlit
20ad0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
20ae0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
20af0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
20b00 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
20b10 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
20b20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
20b30 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
20b40 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
20b50 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
20b60 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
20b70 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
20b80 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
20b90 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
20ba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
20bb0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
20bc0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
20bd0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
20be0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
20bf0 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
20c00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
20c10 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
20c20 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
20c30 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
20c40 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
20c50 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
20c60 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
20c70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
20c80 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
20c90 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
20ca0 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
20cb0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
20cc0 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
20cd0 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
20ce0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
20cf0 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
20d00 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
20d10 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
20d20 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
20d30 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
20d40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
20d50 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
20d60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
20d70 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
20d80 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
20d90 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
20da0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
20db0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
20dc0 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
20dd0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
20de0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
20df0 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
20e00 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
20e10 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
20e20 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
20e30 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
20e40 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
20e50 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
20e60 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
20e70 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
20e80 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
20e90 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
20ea0 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
20eb0 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
20ec0 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
20ed0 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
20ee0 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
20ef0 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
20f00 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
20f10 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
20f20 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
20f30 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
20f40 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
20f50 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
20f60 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
20f70 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
20f80 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
20f90 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
20fa0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
20fb0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
20fc0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
20fd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
20fe0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
20ff0 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
21000 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
21010 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Result.**.** ^Th
21020 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
21030 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
21040 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
21050 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
21060 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
21070 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
21080 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
21090 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
210a0 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
210b0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
210c0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
210d0 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
210e0 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
210f0 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
21100 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
21110 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
21120 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
21130 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
21140 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
21150 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
21160 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
21170 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
21180 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
21190 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
211a0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
211b0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
211c0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
211d0 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
211e0 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
211f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
21200 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
21210 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
21220 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
21230 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
21240 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
21250 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
21260 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
21270 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
21280 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
21290 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
212a0 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
212b0 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
212c0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
212d0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
212e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
212f0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
21300 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
21310 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
21320 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
21330 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
21340 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
21350 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
21360 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
21370 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
21380 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
21390 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
213a0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
213b0 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
213c0 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
213d0 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
213e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
213f0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
21400 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
21410 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
21420 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
21430 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
21440 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
21450 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
21460 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
21470 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
21480 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
21490 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
214a0 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
214b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
214c0 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
214d0 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
214e0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
214f0 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
21500 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
21510 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
21520 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
21530 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
21540 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
21550 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
21560 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
21570 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
21580 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
21590 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
215a0 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
215b0 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
215c0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
215d0 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
215e0 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
215f0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
21600 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
21610 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
21620 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
21630 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
21640 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
21650 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
21660 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
21670 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
21680 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
21690 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
216a0 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
216b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
216c0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
216d0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
216e0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
216f0 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
21700 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
21710 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
21720 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
21730 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
21740 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
21750 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
21760 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
21770 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
21780 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21790 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
217a0 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
217b0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
217c0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
217d0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
217e0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
217f0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
21800 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
21810 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
21820 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
21830 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
21840 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
21850 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
21860 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
21870 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
21880 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
21890 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
218a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
218b0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
218c0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
218d0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
218e0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
218f0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
21900 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
21910 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
21920 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
21930 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
21940 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
21950 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
21960 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
21970 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
21980 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
21990 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
219a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
219b0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
219c0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
219d0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
219e0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
219f0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
21a00 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
21a10 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
21a20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
21a30 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
21a40 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
21a50 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
21a60 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
21a70 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
21a80 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
21a90 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
21aa0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
21ab0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
21ac0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
21ad0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
21ae0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
21af0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
21b00 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
21b10 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
21b20 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
21b30 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
21b40 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
21b50 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
21b60 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
21b70 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
21b80 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
21b90 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
21ba0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
21bb0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
21bc0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
21bd0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
21be0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
21bf0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
21c00 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
21c10 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
21c20 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
21c30 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
21c40 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
21c50 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
21c60 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
21c70 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
21c80 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
21c90 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
21ca0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
21cb0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
21cc0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
21cd0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
21ce0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
21cf0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
21d00 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
21d10 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
21d20 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
21d30 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
21d40 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
21d50 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
21d60 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
21d70 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
21d80 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
21d90 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
21da0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
21db0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
21dc0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
21dd0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
21de0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
21df0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
21e00 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
21e10 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
21e20 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
21e30 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
21e40 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
21e50 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
21e60 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
21e70 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
21e80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21e90 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
21ea0 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
21eb0 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
21ec0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
21ed0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21ee0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
21ef0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
21f00 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
21f10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
21f20 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
21f30 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
21f40 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
21f50 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
21f60 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
21f70 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
21f80 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
21f90 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
21fa0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
21fb0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
21fc0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
21fd0 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
21fe0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
21ff0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
22000 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
22010 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
22020 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
22030 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
22040 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
22050 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
22060 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
22070 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22080 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
22090 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
220a0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
220b0 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
220c0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
220d0 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
220e0 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
220f0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
22100 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
22110 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
22120 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
22130 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
22140 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
22150 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
22160 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
22170 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
22180 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
22190 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
221a0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
221b0 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
221c0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
221d0 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
221e0 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
221f0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
22200 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
22210 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
22220 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
22230 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
22240 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
22250 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
22260 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
22270 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
22280 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
22290 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
222a0 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
222b0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
222c0 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
222d0 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
222e0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
222f0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
22300 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
22310 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
22320 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
22330 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
22340 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
22350 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74  in a.** explicit
22360 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
22370 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
22380 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
22390 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
223a0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
223b0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
223c0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
223d0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
223e0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
223f0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
22400 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
22410 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
22420 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
22430 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
22440 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
22450 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
22460 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22470 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
22480 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
22490 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
224a0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
224b0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
224c0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
224d0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
224e0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
224f0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
22500 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
22510 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
22520 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
22530 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
22540 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
22550 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
22560 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
22570 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
22580 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
22590 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
225a0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
225b0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
225c0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
225d0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
225e0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
225f0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
22600 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
22610 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
22620 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
22630 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
22640 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
22650 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
22660 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
22670 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
22680 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
22690 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
226a0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
226b0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
226c0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
226d0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
226e0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
226f0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
22700 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
22710 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
22720 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
22730 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
22740 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
22750 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
22760 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
22770 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
22780 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
22790 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
227a0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
227b0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
227c0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
227d0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
227e0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
227f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
22800 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
22810 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
22820 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
22830 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
22840 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
22850 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
22860 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
22870 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
22880 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
22890 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
228a0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
228b0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
228c0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
228d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
228e0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
228f0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
22900 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
22910 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
22920 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22930 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
22940 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
22950 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
22960 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
22970 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
22980 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
22990 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
229a0 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
229b0 31 2c 20 69 74 20 77 61 73 20 72 65 71 75 69 72  1, it was requir
229c0 65 64 0a 2a 2a 20 61 66 74 65 72 20 73 71 6c 69  ed.** after sqli
229d0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
229e0 6e 65 64 20 61 6e 79 74 68 69 6e 67 20 6f 74 68  ned anything oth
229f0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
22a00 52 4f 57 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71  ROW] that.** [sq
22a10 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 62  lite3_reset()] b
22a20 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
22a30 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69  any subsequent i
22a40 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
22a50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
22a60 20 46 61 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f   Failure to invo
22a70 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ke [sqlite3_rese
22a80 74 28 29 5d 20 69 6e 20 74 68 69 73 20 77 61 79  t()] in this way
22a90 20 77 6f 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74   would.** result
22aa0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
22ab0 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
22ac0 6f 6d 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  om sqlite3_step(
22ad0 29 2e 20 20 42 75 74 20 61 66 74 65 72 0a 2a 2a  ).  But after.**
22ae0 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
22af0 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
22b00 29 20 62 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20  ) began calling 
22b10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22b20 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ] .** automatica
22b30 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63  lly in this circ
22b40 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 20  umstance rather 
22b50 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
22b60 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
22b70 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79   .**.** <b>Goofy
22b80 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
22b90 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
22ba0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
22bb0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
22bc0 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
22bd0 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
22be0 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
22bf0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
22c00 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
22c10 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
22c20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
22c30 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
22c40 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
22c50 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
22c60 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
22c70 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
22c80 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
22c90 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
22ca0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
22cb0 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
22cc0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
22cd0 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
22ce0 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
22cf0 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
22d00 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
22d10 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
22d20 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
22d30 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
22d40 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
22d50 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
22d60 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
22d70 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
22d80 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
22d90 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
22da0 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
22db0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
22dc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
22dd0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
22de0 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
22df0 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
22e00 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
22e10 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
22e20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
22e30 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
22e40 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
22e50 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
22e60 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
22e70 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
22e80 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
22e90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
22ea0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22eb0 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
22ec0 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
22ed0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
22ee0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
22ef0 50 29 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  P) the number of
22f00 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
22f10 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
22f20 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
22f30 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
22f40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
22f50 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
22f60 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
22f70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22f80 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
22f90 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
22fa0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
22fb0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
22fc0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
22fd0 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
22fe0 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
22ff0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
23000 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
23010 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
23020 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
23030 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
23040 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
23050 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
23060 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
23070 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
23080 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
23090 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
230a0 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
230b0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
230c0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
230d0 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
230e0 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
230f0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
23100 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
23110 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
23120 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
23130 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
23140 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
23150 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
23160 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
23170 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
23180 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
23190 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
231a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
231b0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
231c0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
231d0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
231e0 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
231f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
23200 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
23210 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
23220 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
23230 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
23240 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
23250 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
23260 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
23270 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
23280 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
23290 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
232a0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
232b0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
232c0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
232d0 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
232e0 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
232f0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
23300 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
23310 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
23320 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
23330 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
23340 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
23350 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
23360 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
23370 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
23380 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
23390 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
233a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
233b0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
233c0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
233d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
233e0 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
233f0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
23400 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
23410 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
23420 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
23430 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
23440 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
23450 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
23460 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
23470 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
23480 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
23490 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
234a0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
234b0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
234c0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
234d0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
234e0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
234f0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
23500 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
23510 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
23520 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
23530 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
23540 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
23550 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
23560 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
23570 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
23580 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
23590 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
235a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
235b0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
235c0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
235d0 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
235e0 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
235f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23600 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
23610 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
23620 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
23630 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
23640 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
23650 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
23660 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
23670 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
23680 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
23690 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
236a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
236b0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
236c0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
236d0 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
236e0 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
236f0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
23700 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
23710 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
23720 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
23730 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
23740 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
23750 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
23760 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
23770 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
23780 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
23790 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
237a0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
237b0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
237c0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
237d0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
237e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
237f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
23800 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
23810 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
23820 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
23830 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
23840 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
23850 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
23860 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
23870 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
23880 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
23890 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
238a0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
238b0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
238c0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
238d0 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
238e0 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
238f0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
23900 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
23910 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
23920 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
23930 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
23940 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
23950 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
23960 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
23970 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
23980 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
23990 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
239a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
239b0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
239c0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
239d0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
239e0 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
239f0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
23a00 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
23a10 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
23a20 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
23a30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
23a40 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
23a50 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
23a60 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
23a70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
23a80 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
23a90 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
23aa0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
23ab0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
23ac0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
23ad0 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
23ae0 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
23af0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
23b00 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
23b10 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
23b20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
23b30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
23b40 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
23b50 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
23b60 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
23b70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23b80 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
23b90 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
23ba0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
23bb0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
23bc0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
23bd0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
23be0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
23bf0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
23c00 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74  * ^The value ret
23c10 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
23c20 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
23c30 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68  terminator at th
23c40 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
23c50 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
23c60 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
23c70 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65   returned is the
23c80 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
23c90 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
23ca0 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
23cb0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
23cc0 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
23cd0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
23ce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23cf0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
23d00 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
23d10 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
23d20 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
23d30 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64   zero terminated
23d40 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
23d50 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
23d60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
23d70 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
23d80 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20  ngth BLOB is an 
23d90 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69  arbitrary.** poi
23da0 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65  nter, possibly e
23db0 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ven a NULL point
23dc0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
23dd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23de0 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20  tes16() routine 
23df0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71  is similar to sq
23e00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23e10 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76  es().** but leav
23e20 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  es the result in
23e30 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
23e40 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
23e50 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
23e60 2a 20 5e 54 68 65 20 7a 65 72 6f 20 74 65 72 6d  * ^The zero term
23e70 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e  inator is not in
23e80 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63  cluded in this c
23e90 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ount..**.** ^The
23ea0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
23eb0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
23ec0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
23ed0 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
23ee0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23ef0 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
23f00 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
23f10 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
23f20 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
23f30 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
23f40 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
23f50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
23f60 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
23f70 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
23f80 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
23f90 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
23fa0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
23fb0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
23fc0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
23fd0 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
23fe0 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
23ff0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
24000 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
24010 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
24020 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
24030 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
24040 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
24050 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
24060 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
24070 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
24080 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
24090 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
240a0 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
240b0 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
240c0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
240d0 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
240e0 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
240f0 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
24100 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
24110 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
24120 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
24130 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
24140 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
24150 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
24160 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
24170 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
24180 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
24190 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
241a0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
241b0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
241c0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
241d0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
241e0 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
241f0 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
24200 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
24210 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
24220 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
24230 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
24240 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
24250 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
24260 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
24270 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
24280 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
24290 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
242a0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
242b0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
242c0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
242d0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
242e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
242f0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
24300 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
24310 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
24320 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
24330 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
24340 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
24350 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
24360 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
24370 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
24380 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
24390 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
243a0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
243b0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
243c0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
243d0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
243e0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
243f0 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
24400 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
24410 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
24420 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
24430 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
24440 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
24450 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
24460 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
24470 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
24480 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
24490 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
244a0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
244b0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
244c0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
244d0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
244e0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
244f0 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
24500 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
24510 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
24520 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
24530 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
24540 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
24550 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
24560 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
24570 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
24580 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
24590 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
245a0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
245b0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
245c0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
245d0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
245e0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
245f0 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
24600 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
24610 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
24620 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
24630 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
24640 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
24650 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
24660 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
24670 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
24680 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
24690 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
246a0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
246b0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
246c0 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
246d0 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
246e0 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
246f0 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
24700 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
24710 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
24720 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
24730 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
24740 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
24750 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
24760 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  mers..**.** ^Not
24770 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
24780 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
24790 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
247a0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
247b0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
247c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
247d0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
247e0 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
247f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
24800 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
24810 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
24820 2a 20 5e 28 54 79 70 65 20 63 6f 6e 76 65 72 73  * ^(Type convers
24830 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
24840 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
24850 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
24860 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
24870 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
24880 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
24890 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
248a0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
248b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
248c0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
248d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
248e0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
248f0 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
24900 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
24910 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
24920 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
24930 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
24940 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
24950 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
24960 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
24970 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
24980 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
24990 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
249a0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
249b0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
249c0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
249d0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
249e0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
249f0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
24a00 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
24a10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24a20 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
24a30 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
24a40 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
24a50 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
24a60 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
24a70 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
24a80 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
24a90 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  >)^.**.** ^Conve
24aa0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
24ab0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
24ac0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
24ad0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
24ae0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
24af0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
24b00 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
24b10 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
24b20 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
24b30 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
24b40 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69  rior pointer poi
24b50 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65  nts to will have
24b60 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
24b70 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
24b80 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
24b90 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
24ba0 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
24bb0 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
24bc0 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
24bd0 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
24be0 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
24bf0 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
24c00 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
24c10 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 61 66 65 73  *.** ^(The safes
24c20 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
24c30 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
24c40 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
24c50 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
24c60 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
24c70 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
24c80 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
24c90 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
24ca0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
24cb0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
24cc0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
24cd0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
24ce0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
24cf0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
24d00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
24d10 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
24d20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24d30 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
24d40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24d50 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
24d60 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
24d70 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
24d80 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
24d90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24da0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
24db0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
24dc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
24dd0 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
24de0 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
24df0 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
24e00 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
24e10 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
24e20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24e30 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
24e40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
24e50 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
24e60 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
24e70 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
24e80 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
24e90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
24ea0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
24eb0 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
24ec0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
24ed0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24ee0 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
24ef0 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
24f00 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24f10 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
24f20 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
24f30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
24f40 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
24f50 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
24f60 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
24f70 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
24f80 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
24f90 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
24fa0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
24fb0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
24fc0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
24fd0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
24fe0 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
24ff0 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
25000 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
25010 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
25020 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
25030 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
25040 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
25050 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
25060 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
25070 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
25080 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
25090 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
250a0 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
250b0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
250c0 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
250d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
250e0 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
250f0 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
25100 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
25110 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
25120 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
25130 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
25140 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
25150 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
25160 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
25170 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
25180 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
25190 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
251a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
251b0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
251c0 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
251d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
251e0 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
251f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
25200 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
25210 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
25220 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
25230 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
25240 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
25250 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
25260 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
25270 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25280 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
25290 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
252a0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
252b0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
252c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
252d0 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
252e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
252f0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
25300 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25310 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
25320 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
25330 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
25340 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
25350 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
25360 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
25370 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
25380 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
25390 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
253a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
253b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
253c0 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
253d0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
253e0 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
253f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
25400 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
25410 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
25420 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25430 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
25440 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
25450 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
25460 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
25470 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
25480 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
25490 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
254a0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
254b0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
254c0 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
254d0 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65  fully or not exe
254e0 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68  cuted at all, th
254f0 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20  en.** SQLITE_OK 
25500 69 73 20 72 65 74 75 72 6e 65 64 2e 20 5e 49 66  is returned. ^If
25510 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
25520 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c  e statement fail
25530 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65  ed then an.** [e
25540 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65  rror code] or [e
25550 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
25560 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
25570 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
25580 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
25590 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
255a0 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75  during the execu
255b0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  tion of the.** [
255c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
255d0 6e 74 5d 2e 20 20 5e 49 66 20 74 68 65 20 76 69  nt].  ^If the vi
255e0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61  rtual machine ha
255f0 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s not.** complet
25600 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65  ed execution whe
25610 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  n this routine i
25620 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69  s called, that i
25630 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e  s like.** encoun
25640 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20  tering an error 
25650 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  or an [sqlite3_i
25660 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
25670 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d  rupt]..** ^Incom
25680 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61  plete updates ma
25690 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  y be rolled back
256a0 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e   and transaction
256b0 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64  s canceled,.** d
256c0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
256d0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61  circumstances, a
256e0 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72  nd the.** [error
256f0 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20   code] returned 
25700 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  will be [SQLITE_
25710 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ABORT]..*/.int s
25720 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
25730 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
25740 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
25750 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
25760 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
25770 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
25780 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
25790 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
257a0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
257b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
257c0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
257d0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
257e0 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
257f0 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
25800 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
25810 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
25820 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
25830 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
25840 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
25850 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25860 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
25870 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
25880 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
25890 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
258a0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
258b0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
258c0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
258d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
258e0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
258f0 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
25900 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25910 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
25920 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
25930 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
25940 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
25950 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
25960 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
25970 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
25980 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25990 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
259a0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
259b0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
259c0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
259d0 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
259e0 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
259f0 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
25a00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
25a10 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
25a20 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
25a30 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
25a40 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25a50 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
25a60 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
25a70 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
25a80 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
25a90 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
25aa0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
25ab0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
25ac0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
25ad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
25ae0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
25af0 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
25b00 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
25b10 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
25b20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25b30 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
25b40 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25b50 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
25b60 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
25b70 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
25b80 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
25b90 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
25ba0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
25bb0 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
25bc0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
25bd0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
25be0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
25bf0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
25c00 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
25c10 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
25c20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
25c30 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
25c40 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 74  }.**.** ^These t
25c50 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  wo functions (co
25c60 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
25c70 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
25c80 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
25c90 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
25ca0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
25cb0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
25cc0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
25cd0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
25ce0 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
25cf0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
25d00 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
25d10 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65  ly difference be
25d20 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f  tween the.** two
25d30 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63   is that the sec
25d40 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ond parameter, t
25d50 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  he name of the (
25d60 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
25d70 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
25d80 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20  , is encoded in 
25d90 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65  UTF-8 for sqlite
25da0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
25db0 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a  n() and UTF-16.*
25dc0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
25dd0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
25de0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  )..**.** ^The fi
25df0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
25e00 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
25e10 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
25e20 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
25e30 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
25e40 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
25e50 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
25e60 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
25e70 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
25e80 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
25e90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
25ea0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
25eb0 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
25ec0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
25ed0 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
25ee0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tely..**.** The 
25ef0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
25f00 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
25f10 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
25f20 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
25f30 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
25f40 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
25f50 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
25f60 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
25f70 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a  , exclusive of.*
25f80 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  * the zero-termi
25f90 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61  nator.  Note tha
25fa0 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74  t the name lengt
25fb0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79  h limit is in by
25fc0 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72  tes, not.** char
25fd0 61 63 74 65 72 73 2e 20 20 5e 41 6e 79 20 61 74  acters.  ^Any at
25fe0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
25ff0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
26000 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
26010 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
26020 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62  [SQLITE_ERROR] b
26030 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
26040 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
26050 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
26060 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
26070 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
26080 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
26090 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
260a0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
260b0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
260c0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
260d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
260e0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
260f0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
26100 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
26110 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
26120 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
26130 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
26140 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
26150 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
26160 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
26170 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
26180 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
26190 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
261a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
261b0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
261c0 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
261d0 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
261e0 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
261f0 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
26200 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
26210 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
26220 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
26230 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
26240 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
26250 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
26260 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
26270 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
26280 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
26290 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
262a0 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
262b0 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
262c0 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
262d0 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
262e0 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
262f0 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e  an another.  ^An
26300 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
26310 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
26320 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
26330 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
26340 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
26350 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  6() multiple.** 
26360 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
26370 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74  ame function but
26380 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
26390 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52  values of eTextR
263a0 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c  ep..** ^When mul
263b0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
263c0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
263d0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
263e0 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
263f0 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
26400 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
26410 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
26420 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
26430 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
26440 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
26450 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
26460 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
26470 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65  not care what te
26480 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69  xt.** encoding i
26490 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
264a0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
264b0 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49   should be [SQLI
264c0 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  TE_ANY]..**.** ^
264d0 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
264e0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
264f0 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
26500 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
26510 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
26520 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
26530 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
26540 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
26550 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
26560 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .)^.**.** The se
26570 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
26580 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
26590 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
265a0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
265b0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
265c0 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
265d0 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
265e0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
265f0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
26600 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
26610 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
26620 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
26630 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
26640 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
26650 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
26660 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70  ters should be p
26670 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
26680 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
26690 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
266a0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
266b0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
266c0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
266d0 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
266e0 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
266f0 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  LL should be pas
26700 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
26710 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
26720 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
26730 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
26740 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f  te, pass NULL fo
26750 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
26760 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  tion callbacks..
26770 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
26780 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
26790 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
267a0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
267b0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
267c0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
267d0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
267e0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
267f0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
26800 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
26810 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
26820 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
26830 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
26840 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
26850 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
26860 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
26870 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
26880 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
26890 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
268a0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
268b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
268c0 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
268d0 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
268e0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
268f0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
26900 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
26910 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
26920 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
26930 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
26940 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
26950 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
26960 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
26970 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
26980 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
26990 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
269a0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
269b0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
269c0 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
269d0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
269e0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
269f0 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
26a00 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
26a10 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
26a20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
26a30 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
26a40 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
26a50 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
26a60 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
26a70 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
26a80 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
26a90 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
26aa0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
26ab0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
26ac0 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ns..** ^The firs
26ad0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  t application-de
26ae0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77  fined function w
26af0 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65  ith a given name
26b00 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a   overrides all.*
26b10 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74  * built-in funct
26b20 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65  ions in the same
26b30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
26b40 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20  ction] with the 
26b50 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53  same name..** ^S
26b60 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63  ubsequent applic
26b70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26b80 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  nctions of the s
26b90 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76  ame name only ov
26ba0 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72  erride .** prior
26bb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
26bc0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74  ined functions t
26bd0 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74  hat are an exact
26be0 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a   match for the.*
26bf0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61  * number of para
26c00 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65  meters and prefe
26c10 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rred encoding..*
26c20 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
26c30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
26c40 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
26c50 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
26c60 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
26c70 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
26c80 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
26c90 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
26ca0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
26cb0 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
26cc0 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
26cd0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
26ce0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
26cf0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
26d00 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
26d10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26d20 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
26d30 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
26d40 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
26d50 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
26d60 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
26d70 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
26d80 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
26d90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
26da0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
26db0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
26dc0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
26dd0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
26de0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
26df0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
26e00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
26e10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
26e20 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
26e30 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
26e40 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
26e50 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
26e60 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
26e70 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
26e80 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
26e90 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
26ea0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
26eb0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
26ec0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
26ed0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
26ee0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
26ef0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
26f00 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
26f10 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  ntext*).);../*.*
26f20 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
26f30 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
26f40 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
26f50 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
26f60 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
26f70 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
26f80 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
26f90 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
26fa0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
26fb0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
26fc0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
26fd0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
26fe0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
26ff0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
27000 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
27010 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
27020 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
27030 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
27040 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
27050 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
27060 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
27070 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
27080 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
27090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
270a0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
270b0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
270c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
270d0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
270e0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
270f0 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
27100 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
27110 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
27120 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
27130 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
27140 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
27150 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
27160 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
27170 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
27180 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
27190 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
271a0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
271b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
271c0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
271d0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
271e0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
271f0 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
27200 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
27210 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
27220 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
27230 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
27240 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
27250 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
27260 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
27270 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
27280 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
27290 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
272a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
272b0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
272c0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
272d0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
272e0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
272f0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
27300 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
27310 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
27320 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
27330 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
27340 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
27350 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
27360 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
27370 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
27380 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
27390 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
273a0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
273b0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
273c0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
273d0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
273e0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
273f0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
27400 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
27410 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
27420 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
27430 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
27440 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
27450 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
27460 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
27470 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
27480 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
27490 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
274a0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
274b0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
274c0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
274d0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
274e0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
274f0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
27500 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
27510 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
27520 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
27530 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
27540 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
27550 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
27560 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
27570 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
27580 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
27590 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
275a0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
275b0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
275c0 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
275d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
275e0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
275f0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
27600 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
27610 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27620 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
27630 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
27640 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
27650 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
27660 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
27670 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
27680 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
27690 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
276a0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
276b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
276c0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
276d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
276e0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
276f0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
27700 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
27710 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
27720 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
27730 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
27740 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
27750 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
27760 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
27770 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
27780 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
27790 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
277a0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
277b0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
277c0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
277d0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
277e0 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
277f0 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
27800 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
27810 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
27820 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
27830 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
27840 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
27850 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
27860 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
27870 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27880 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
27890 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
278a0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
278b0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
278c0 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
278d0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
278e0 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
278f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27900 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
27910 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
27920 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
27930 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
27940 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
27950 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
27960 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
27970 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
27980 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
27990 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
279a0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
279b0 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
279c0 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
279d0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
279e0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
279f0 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
27a00 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
27a10 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
27a20 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
27a30 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
27a40 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
27a50 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
27a60 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
27a70 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
27a80 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
27a90 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
27aa0 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
27ab0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
27ac0 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
27ad0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
27ae0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
27af0 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
27b00 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
27b10 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
27b20 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
27b30 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
27b40 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
27b50 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
27b60 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
27b70 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
27b80 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
27b90 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
27ba0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
27bb0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
27bc0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
27bd0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
27be0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
27bf0 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
27c00 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
27c10 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
27c20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
27c30 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
27c40 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
27c50 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
27c60 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
27c70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
27c80 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
27c90 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
27ca0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
27cb0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
27cc0 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
27cd0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
27ce0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
27cf0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
27d00 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
27d10 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
27d20 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
27d30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
27d40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
27d50 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
27d60 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
27d70 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
27d80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27d90 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
27da0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
27db0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
27dc0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
27dd0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
27de0 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
27df0 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
27e00 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
27e10 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
27e20 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
27e30 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
27e40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27e50 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27e60 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
27e70 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
27e80 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
27e90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
27ea0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
27eb0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
27ec0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
27ed0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
27ee0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
27ef0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
27f00 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
27f10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
27f20 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
27f30 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
27f40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27f50 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
27f60 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
27f70 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
27f80 65 6d 65 6e 74 69 6f 6e 73 20 6f 66 20 61 67 67  ementions of agg
27f90 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
27fa0 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
27fb0 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
27fc0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
27fd0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
27fe0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
27ff0 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
28000 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
28010 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
28020 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
28030 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
28040 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
28050 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
28060 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
28070 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
28080 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
28090 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
280a0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
280b0 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
280c0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
280d0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
280e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
280f0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
28100 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
28110 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
28120 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
28130 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
28140 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
28150 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
28160 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
28170 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
28180 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
28190 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
281a0 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
281b0 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
281c0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
281d0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
281e0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
281f0 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
28200 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
28210 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
28220 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
28230 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
28240 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
28250 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
28260 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
28270 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
28280 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
28290 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
282a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
282b0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
282c0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
282d0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
282e0 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
282f0 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
28300 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
28310 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
28320 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
28330 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
28340 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c  ter if N is.** l
28350 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
28360 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
28370 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
28380 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
28390 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
283a0 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
283b0 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
283c0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
283d0 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
283e0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
283f0 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
28400 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
28410 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
28420 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
28430 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
28440 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
28450 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
28460 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
28470 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
28480 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
28490 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
284a0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
284b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a   allocation.)^.*
284c0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
284d0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
284e0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
284f0 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
28500 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
28510 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
28520 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
28530 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
28540 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
28550 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
28560 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
28570 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
28580 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
28590 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
285a0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
285b0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
285c0 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
285d0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
285e0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
285f0 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
28600 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
28610 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
28620 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
28630 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
28640 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
28650 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
28660 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
28670 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
28680 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
28690 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
286a0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
286b0 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
286c0 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
286d0 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
286e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
286f0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
28700 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28710 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
28720 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
28730 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
28740 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
28750 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
28760 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
28770 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
28780 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
28790 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
287a0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
287b0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
287c0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
287d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
287e0 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
287f0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
28800 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
28810 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
28820 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
28830 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
28840 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
28850 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
28860 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
28870 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
28880 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
28890 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
288a0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
288b0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
288c0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
288d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
288e0 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
288f0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
28900 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
28910 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
28920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28930 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
28940 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
28950 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28960 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
28970 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
28980 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
28990 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
289a0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
289b0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
289c0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
289d0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
289e0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
289f0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
28a00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28a10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
28a20 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
28a30 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
28a40 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
28a50 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
28a60 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
28a70 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
28a80 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
28a90 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
28aa0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
28ab0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
28ac0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
28ad0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
28ae0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
28af0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
28b00 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
28b10 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
28b20 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
28b30 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
28b40 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
28b50 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
28b60 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
28b70 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
28b80 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
28b90 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
28ba0 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
28bb0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
28bc0 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
28bd0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
28be0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
28bf0 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
28c00 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
28c10 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
28c20 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
28c30 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
28c40 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
28c50 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
28c60 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
28c70 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
28c80 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
28c90 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
28ca0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
28cb0 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
28cc0 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
28cd0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
28ce0 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
28cf0 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
28d00 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
28d10 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
28d20 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
28d30 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
28d40 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
28d50 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
28d60 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
28d70 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
28d80 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
28d90 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
28da0 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
28db0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
28dc0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
28dd0 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
28de0 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
28df0 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
28e00 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
28e10 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
28e20 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
28e30 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
28e40 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
28e50 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
28e60 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
28e70 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
28e80 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
28e90 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
28ea0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
28eb0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
28ec0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
28ed0 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
28ee0 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
28ef0 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
28f00 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
28f10 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
28f20 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
28f30 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
28f40 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
28f50 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
28f60 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
28f70 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
28f80 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
28f90 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
28fa0 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
28fb0 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
28fc0 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
28fd0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
28fe0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
28ff0 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
29000 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
29010 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
29020 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
29030 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
29040 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
29050 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
29060 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
29070 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
29080 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
29090 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
290a0 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
290b0 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
290c0 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
290d0 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
290e0 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
290f0 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
29100 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
29110 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
29120 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
29130 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
29140 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
29150 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
29160 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
29170 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
29180 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
29190 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
291a0 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
291b0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
291c0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
291d0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
291e0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
291f0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
29200 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
29210 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
29220 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
29230 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
29240 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
29250 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
29260 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
29270 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
29280 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
29290 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
292a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
292b0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
292c0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
292d0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
292e0 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
292f0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
29300 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
29310 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
29320 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
29330 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
29340 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
29350 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
29360 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
29370 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
29380 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
29390 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
293a0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
293b0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
293c0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
293d0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
293e0 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
293f0 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
29400 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
29410 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
29420 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
29430 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
29440 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
29450 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
29460 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
29470 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
29480 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
29490 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
294a0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
294b0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
294c0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
294d0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
294e0 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
294f0 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
29500 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
29510 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
29520 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
29530 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
29540 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
29550 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
29560 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
29570 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
29580 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
29590 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
295a0 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
295b0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
295c0 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
295d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
295e0 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
295f0 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
29600 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
29610 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
29620 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
29630 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
29640 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
29650 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
29660 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
29670 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
29680 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
29690 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
296a0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
296b0 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
296c0 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
296d0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
296e0 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
296f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29700 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
29710 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29720 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
29730 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
29740 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
29750 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
29760 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
29770 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
29780 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
29790 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
297a0 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
297b0 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
297c0 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
297d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
297e0 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
297f0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
29800 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
29810 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
29820 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
29830 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
29840 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
29850 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
29860 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
29870 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29880 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
29890 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
298a0 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
298b0 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
298c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
298d0 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
298e0 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
298f0 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
29900 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
29910 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29920 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
29930 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
29940 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
29950 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
29960 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
29970 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
29980 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
29990 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
299a0 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
299b0 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
299c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
299d0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
299e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
299f0 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
29a00 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
29a10 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
29a20 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
29a30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29a40 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
29a50 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
29a60 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
29a70 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
29a80 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
29a90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29aa0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
29ab0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
29ac0 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
29ad0 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
29ae0 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
29af0 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
29b00 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
29b10 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
29b20 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
29b30 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
29b40 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
29b50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29b60 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
29b70 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
29b80 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
29b90 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
29ba0 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
29bb0 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
29bc0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
29bd0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
29be0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
29bf0 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
29c00 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
29c10 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
29c20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29c30 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
29c40 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
29c50 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
29c60 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
29c70 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
29c80 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
29c90 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
29ca0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
29cb0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
29cc0 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
29cd0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
29ce0 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
29cf0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
29d00 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
29d10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
29d20 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
29d30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29d40 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
29d50 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29d60 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
29d70 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
29d80 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
29d90 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
29da0 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
29db0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
29dc0 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
29dd0 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
29de0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29df0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
29e00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
29e10 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
29e20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
29e30 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
29e40 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
29e50 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
29e60 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
29e70 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
29e80 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
29e90 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
29ea0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
29eb0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
29ec0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
29ed0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29ee0 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
29ef0 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
29f00 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
29f10 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
29f20 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
29f30 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
29f40 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
29f50 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
29f60 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
29f70 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
29f80 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
29f90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29fa0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
29fb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29fc0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
29fd0 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
29fe0 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
29ff0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a000 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
2a010 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2a020 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
2a030 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
2a040 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
2a050 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
2a060 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
2a070 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
2a080 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a090 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  t_nomem() interf
2a0a0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
2a0b0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
2a0c0 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
2a0d0 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
2a0e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
2a0f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2a100 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2a110 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2a120 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2a130 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2a140 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2a150 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2a160 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
2a170 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
2a180 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
2a190 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2a1a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2a1b0 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
2a1c0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2a1d0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2a1e0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2a1f0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2a200 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
2a210 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
2a220 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
2a230 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
2a240 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
2a250 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a260 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
2a270 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2a280 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2a290 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2a2a0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2a2b0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
2a2c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2a2d0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
2a2e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a2f0 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
2a300 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
2a310 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
2a320 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
2a330 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
2a340 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
2a350 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
2a360 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2a370 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
2a380 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
2a390 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
2a3a0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
2a3b0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
2a3c0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
2a3d0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
2a3e0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
2a3f0 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
2a400 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
2a410 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
2a420 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
2a430 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
2a440 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
2a450 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
2a460 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a470 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
2a480 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
2a490 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2a4a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2a4b0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2a4c0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2a4d0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
2a4e0 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
2a4f0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
2a500 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
2a510 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
2a520 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
2a530 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
2a540 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2a550 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2a560 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
2a570 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
2a580 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
2a590 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
2a5a0 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
2a5b0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
2a5c0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2a5d0 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
2a5e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2a5f0 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
2a600 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
2a610 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2a620 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2a630 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2a640 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
2a650 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2a660 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
2a670 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
2a680 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
2a690 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
2a6a0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
2a6b0 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
2a6c0 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
2a6d0 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
2a6e0 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
2a6f0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
2a700 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2a710 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2a720 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2a730 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
2a740 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2a750 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
2a760 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
2a770 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
2a780 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
2a790 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
2a7a0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
2a7b0 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
2a7c0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
2a7d0 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
2a7e0 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
2a7f0 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
2a800 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
2a810 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
2a820 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
2a830 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
2a840 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
2a850 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2a860 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2a870 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2a880 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
2a890 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
2a8a0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
2a8b0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
2a8c0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
2a8d0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
2a8e0 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
2a8f0 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
2a900 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
2a910 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2a920 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
2a930 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2a940 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a950 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
2a960 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2a970 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
2a980 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2a990 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2a9a0 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
2a9b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2a9c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2a9d0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
2a9e0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2a9f0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
2aa00 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2aa10 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
2aa20 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2aa30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
2aa40 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
2aa50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
2aa60 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
2aa70 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
2aa80 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
2aa90 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
2aaa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2aab0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
2aac0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
2aad0 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
2aae0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2aaf0 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
2ab00 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
2ab10 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2ab20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2ab30 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
2ab40 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
2ab50 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
2ab60 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
2ab70 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
2ab80 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
2ab90 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
2aba0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2abb0 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
2abc0 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
2abd0 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
2abe0 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
2abf0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2ac00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2ac10 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
2ac20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2ac30 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
2ac40 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2ac50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
2ac60 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2ac70 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
2ac80 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2ac90 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2aca0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2acb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2acc0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
2acd0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
2ace0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2acf0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
2ad00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2ad10 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
2ad20 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2ad30 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
2ad40 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2ad50 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
2ad60 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2ad70 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
2ad80 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
2ad90 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2ada0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2adb0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
2adc0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2add0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2ade0 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
2adf0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
2ae00 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2ae10 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
2ae20 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
2ae30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2ae40 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
2ae50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
2ae60 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
2ae70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2ae80 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
2ae90 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2aea0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2aeb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2aec0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
2aed0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2aee0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2aef0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2af00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2af10 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2af20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2af30 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2af40 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2af50 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2af60 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2af70 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
2af80 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2af90 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2afa0 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
2afb0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2afc0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
2afd0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2afe0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2aff0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2b000 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
2b010 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
2b020 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
2b030 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
2b040 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
2b050 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
2b060 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
2b070 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
2b080 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2b090 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  s are used to ad
2b0a0 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  d new collation 
2b0b0 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65  sequences to the
2b0c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
2b0d0 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
2b0e0 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
2b0f0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2b100 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
2b110 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
2b120 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
2b130 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
2b140 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
2b150 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2b160 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
2b170 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2b180 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
2b190 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
2b1a0 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
2b1b0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2b1c0 36 28 29 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73  6(). ^In all cas
2b1d0 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69  es.** the name i
2b1e0 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
2b1f0 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
2b200 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2b210 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
2b220 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ent may be one o
2b230 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20  f the constants 
2b240 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
2b250 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
2b260 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2b270 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74  TF16BE], indicat
2b280 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65  ing that the use
2b290 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f  r-supplied.** ro
2b2a0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f  utine expects to
2b2b0 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74   be passed point
2b2c0 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65  ers to strings e
2b2d0 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
2b2e0 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  -8,.** UTF-16 li
2b2f0 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle-endian, or 
2b300 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
2b310 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
2b320 20 5e 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61   ^The.** third a
2b330 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c  rgument might al
2b340 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54  so be [SQLITE_UT
2b350 46 31 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65  F16] to indicate
2b360 20 74 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e   that the routin
2b370 65 0a 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69  e.** expects poi
2b380 6e 74 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d  nters to be UTF-
2b390 31 36 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  16 strings in th
2b3a0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2b3b0 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61  der, or the.** a
2b3c0 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b  rgument can be [
2b3d0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2b3e0 47 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20  GNED] if the.** 
2b3f0 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65  the routine expe
2b400 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  cts pointers to 
2b410 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67  16-bit word alig
2b420 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f  ned strings.** o
2b430 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  f UTF-16 in the 
2b440 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2b450 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74  r..**.** A point
2b460 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73  er to the user s
2b470 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20  upplied routine 
2b480 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
2b490 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61  s the fifth.** a
2b4a0 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74  rgument.  ^If it
2b4b0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69   is NULL, this i
2b4c0 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65  s the same as de
2b4d0 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61  leting the colla
2b4e0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2b4f0 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65   (so that SQLite
2b500 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20   cannot call it 
2b510 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61  anymore)..** ^Ea
2b520 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
2b530 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64  ication supplied
2b540 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
2b550 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
2b560 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72  ed.** as its fir
2b570 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63  st parameter a c
2b580 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
2b590 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2b5a0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
2b5b0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  * to sqlite3_cre
2b5c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
2b5d0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2b5e0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
2b5f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61  .**.** ^The rema
2b600 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20  ining arguments 
2b610 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
2b620 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74  on-supplied rout
2b630 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69  ine are two stri
2b640 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70  ngs,.** each rep
2b650 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c  resented by a (l
2b660 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69  ength, data) pai
2b670 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e  r and encoded in
2b680 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a   the encoding.**
2b690 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64   that was passed
2b6a0 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72   as the third ar
2b6b0 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20  gument when the 
2b6c0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2b6d0 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74  ce was.** regist
2b6e0 65 72 65 64 2e 20 20 54 68 65 20 61 70 70 6c 69  ered.  The appli
2b6f0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63  cation defined c
2b700 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  ollation routine
2b710 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
2b720 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  n negative, zero
2b730 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20   or positive if 
2b740 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
2b750 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a   is less than,.*
2b760 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  * equal to, or g
2b770 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
2b780 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69  second string. i
2b790 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53  .e. (STRING1 - S
2b7a0 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e  TRING2)..**.** ^
2b7b0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
2b7c0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2b7d0 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
2b7e0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2b7f0 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70  ation().** excep
2b800 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20  t that it takes 
2b810 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e  an extra argumen
2b820 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73  t which is a des
2b830 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74  tructor for.** t
2b840 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e  he collation.  ^
2b850 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2b860 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  s called when th
2b870 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a  e collation is.*
2b880 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20  * destroyed and 
2b890 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
2b8a0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
2b8b0 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70  arameter void* p
2b8c0 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65  ointer.** of the
2b8d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b8e0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a  collation_v2()..
2b8f0 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20 61  ** ^Collations a
2b900 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65  re destroyed whe
2b910 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
2b920 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63  idden by later c
2b930 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63  alls to the.** c
2b940 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
2b950 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
2b960 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73  hen the [databas
2b970 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
2b980 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67   closed.** using
2b990 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2b9a0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2b9b0 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
2b9c0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2b9d0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2b9e0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2b9f0 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
2ba00 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2ba10 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
2ba20 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
2ba30 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
2ba40 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
2ba50 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
2ba60 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2ba70 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2ba80 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
2ba90 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2baa0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
2bab0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
2bac0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2bad0 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
2bae0 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
2baf0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
2bb00 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2bb10 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2bb20 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
2bb30 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
2bb40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2bb50 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2bb60 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2bb70 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
2bb80 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
2bb90 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2bba0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2bbb0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2bbc0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2bbd0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2bbe0 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
2bbf0 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
2bc00 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
2bc10 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
2bc20 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
2bc30 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2bc40 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
2bc50 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
2bc60 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
2bc70 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
2bc80 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
2bc90 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
2bca0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2bcb0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2bcc0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
2bcd0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
2bce0 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
2bcf0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
2bd00 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
2bd10 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
2bd20 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
2bd30 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2bd40 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
2bd50 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
2bd60 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
2bd70 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2bd80 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
2bd90 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
2bda0 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
2bdb0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2bdc0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
2bdd0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
2bde0 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
2bdf0 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
2be00 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
2be10 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
2be20 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
2be30 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
2be40 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
2be50 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
2be60 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
2be70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
2be80 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
2be90 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
2bea0 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
2beb0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2bec0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
2bed0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2bee0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2bef0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2bf00 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
2bf10 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2bf20 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2bf30 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
2bf40 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2bf50 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2bf60 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
2bf70 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
2bf80 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
2bf90 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
2bfa0 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
2bfb0 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
2bfc0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2bfd0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2bfe0 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
2bff0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2c000 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
2c010 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
2c020 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
2c030 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
2c040 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
2c050 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
2c060 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
2c070 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2c080 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2c090 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
2c0a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2c0b0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
2c0c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2c0d0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
2c0e0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2c0f0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
2c100 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2c110 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
2c120 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
2c130 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
2c140 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
2c150 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2c160 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
2c170 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2c180 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
2c190 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
2c1a0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
2c1b0 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
2c1c0 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
2c1d0 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
2c1e0 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
2c1f0 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
2c200 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
2c210 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
2c220 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
2c230 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
2c240 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2c250 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2c260 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2c270 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2c280 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2c290 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2c2a0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
2c2b0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2c2c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c2d0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2c2e0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2c2f0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2c300 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2c310 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
2c320 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
2c330 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
2c340 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
2c350 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
2c360 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
2c370 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
2c380 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
2c390 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
2c3a0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
2c3b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
2c3c0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
2c3d0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2c3e0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2c3f0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2c400 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2c410 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2c420 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
2c430 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
2c440 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2c450 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2c460 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2c470 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2c480 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2c490 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2c4a0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
2c4b0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
2c4c0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
2c4d0 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
2c4e0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
2c4f0 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
2c500 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
2c510 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
2c520 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2c530 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
2c540 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
2c550 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
2c560 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
2c570 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
2c580 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
2c590 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
2c5a0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2c5b0 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
2c5c0 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
2c5d0 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
2c5e0 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
2c5f0 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
2c600 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
2c610 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2c620 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64  3_activate_cerod
2c630 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
2c640 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
2c650 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
2c660 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
2c670 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2c680 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
2c690 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
2c6a0 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ort Time.**.** ^
2c6b0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
2c6c0 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
2c6d0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
2c6e0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
2c6f0 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
2c700 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
2c710 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2c720 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
2c730 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
2c740 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  .**.** ^If the o
2c750 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
2c760 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
2c770 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
2c780 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
2c790 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
2c7a0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
2c7b0 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
2c7c0 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
2c7d0 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
2c7e0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  ^The number of m
2c7f0 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
2c800 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
2c810 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
2c820 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2c830 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
2c840 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
2c850 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
2c860 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
2c870 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
2c880 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
2c890 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
2c8a0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
2c8b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2c8c0 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
2c8d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2c8e0 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
2c8f0 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
2c900 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
2c910 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
2c920 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
2c930 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
2c940 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
2c950 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
2c960 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
2c970 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
2c980 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
2c990 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
2c9a0 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
2c9b0 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
2c9c0 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
2c9d0 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
2c9e0 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
2c9f0 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
2ca00 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2ca10 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2ca20 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
2ca30 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
2ca40 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
2ca50 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
2ca60 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
2ca70 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
2ca80 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
2ca90 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2caa0 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
2cab0 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
2cac0 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
2cad0 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
2cae0 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
2caf0 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
2cb00 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2cb10 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
2cb20 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
2cb30 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
2cb40 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
2cb50 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
2cb60 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
2cb70 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
2cb80 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
2cb90 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
2cba0 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
2cbb0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
2cbc0 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
2cbd0 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
2cbe0 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
2cbf0 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
2cc00 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
2cc10 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
2cc20 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72   ^The [temp_stor
2cc30 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2cc40 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
2cc50 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
2cc60 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
2cc70 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
2cc80 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2cc90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
2cca0 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
2ccb0 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * the [temp_stor
2ccc0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2ccd0 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
2cce0 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
2ccf0 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
2cd00 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
2cd10 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
2cd20 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2cd30 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
2cd40 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
2cd50 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
2cd60 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
2cd70 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
2cd80 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
2cd90 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
2cda0 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
2cdb0 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
2cdc0 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
2cdd0 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
2cde0 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
2cdf0 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
2ce00 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2ce10 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
2ce20 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
2ce30 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  f the [temp_stor
2ce40 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2ce50 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
2ce60 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oided..*/.SQLITE
2ce70 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
2ce80 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
2ce90 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
2cea0 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
2ceb0 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
2cec0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2ced0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
2cee0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2cef0 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
2cf00 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
2cf10 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
2cf20 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
2cf30 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
2cf40 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
2cf50 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
2cf60 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
2cf70 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41  espectively.  ^A
2cf80 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2cf90 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
2cfa0 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
2cfb0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
2cfc0 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
2cfd0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74  atement..** ^Aut
2cfe0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2cff0 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
2d000 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
2d010 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
2d020 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
2d030 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
2d040 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
2d050 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
2d060 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
2d070 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
2d080 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
2d090 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
2d0a0 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
2d0b0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
2d0c0 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
2d0d0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
2d0e0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
2d0f0 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
2d100 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
2d110 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
2d120 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
2d130 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
2d140 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
2d150 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2d160 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2d170 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
2d180 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
2d190 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
2d1a0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
2d1b0 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
2d1c0 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
2d1d0 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
2d1e0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2d1f0 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
2d200 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
2d210 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
2d220 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64   value.** is und
2d230 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
2d240 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
2d250 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
2d260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d270 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62  : Find The Datab
2d280 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
2d290 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2d2a0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  nt.**.** ^The sq
2d2b0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
2d2c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2d2d0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
2d2e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
2d2f0 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
2d300 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d310 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
2d320 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63  ^The [database c
2d330 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65  onnection].** re
2d340 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2d350 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
2d360 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2d370 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
2d380 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
2d390 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
2d3a0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2d3b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
2d3c0 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
2d3d0 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
2d3e0 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
2d3f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
2d400 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
2d410 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
2d420 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
2d430 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2d440 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d450 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
2d460 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d470 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
2d480 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d490 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2d4a0 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
2d4b0 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
2d4c0 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
2d4d0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
2d4e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d4f0 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
2d500 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
2d510 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
2d520 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2d530 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
2d540 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
2d550 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
2d560 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
2d570 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2d580 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
2d590 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2d5a0 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
2d5b0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
2d5c0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
2d5d0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
2d5e0 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
2d5f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
2d600 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
2d610 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2d620 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
2d630 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
2d640 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
2d650 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
2d660 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
2d670 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
2d680 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73  LL pointer..*/.s
2d690 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
2d6a0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
2d6b0 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
2d6c0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2d6d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d6e0 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
2d6f0 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
2d700 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
2d710 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d720 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
2d730 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2d740 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
2d750 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
2d760 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2d770 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
2d780 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
2d790 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
2d7a0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2d7b0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2d7c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
2d7d0 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
2d7e0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2d7f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d800 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2d810 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
2d820 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
2d830 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2d840 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
2d850 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
2d860 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2d870 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2d880 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
2d890 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
2d8a0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2d8b0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2d8c0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
2d8d0 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
2d8e0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
2d8f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d900 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
2d910 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
2d920 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
2d930 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
2d940 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
2d950 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
2d960 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
2d970 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
2d980 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
2d990 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
2d9a0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2d9b0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2d9c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
2d9d0 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
2d9e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
2d9f0 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
2da00 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
2da10 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
2da20 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
2da30 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
2da40 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
2da50 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
2da60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2da70 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
2da80 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
2da90 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
2daa0 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
2dab0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
2dac0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2dad0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2dae0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2daf0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2db00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2db10 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2db20 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
2db30 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
2db40 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2db50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
2db60 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
2db70 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
2db80 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
2db90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2dba0 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
2dbb0 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
2dbc0 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
2dbd0 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
2dbe0 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
2dbf0 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
2dc00 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2dc10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
2dc20 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
2dc30 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
2dc40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
2dc50 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
2dc60 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
2dc70 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
2dc80 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67  .** ^Registering
2dc90 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
2dca0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
2dcb0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57  llback..**.** ^W
2dcc0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
2dcd0 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  ook callback rou
2dce0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
2dcf0 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a  o, the [COMMIT].
2dd00 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ** operation is 
2dd10 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69  allowed to conti
2dd20 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e  nue normally.  ^
2dd30 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  If the commit ho
2dd40 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f  ok.** returns no
2dd50 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
2dd60 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e   [COMMIT] is con
2dd70 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52  verted into a [R
2dd80 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68  OLLBACK]..** ^Th
2dd90 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  e rollback hook 
2dda0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20  is invoked on a 
2ddb0 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65  rollback that re
2ddc0 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d  sults from a com
2ddd0 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75  mit.** hook retu
2dde0 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  rning non-zero, 
2ddf0 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64  just as it would
2de00 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68   be with any oth
2de10 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  er rollback..**.
2de20 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
2de30 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
2de40 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
2de50 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
2de60 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
2de70 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
2de80 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
2de90 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
2dea0 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
2deb0 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
2dec0 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
2ded0 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
2dee0 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20   occur..** ^The 
2def0 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
2df00 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
2df10 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
2df20 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
2df30 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
2df40 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
2df50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2df60 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
2df70 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
2df80 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
2df90 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
2dfa0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
2dfb0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2dfc0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
2dfd0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
2dfe0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
2dff0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
2e000 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
2e010 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
2e020 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e030 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
2e040 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2e050 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
2e060 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2e070 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2e080 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2e090 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
2e0a0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
2e0b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2e0c0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2e0d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
2e0e0 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2e0f0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
2e100 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2e110 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2e120 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
2e130 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2e140 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
2e150 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
2e160 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2e170 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2e180 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
2e190 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2e1a0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2e1b0 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
2e1c0 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
2e1d0 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20  hen a.** row is 
2e1e0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
2e1f0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
2e200 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2e210 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
2e220 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
2e230 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
2e240 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
2e250 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2e260 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  ..** ^The second
2e270 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
2e280 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2e290 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
2e2a0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
2e2b0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
2e2c0 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
2e2d0 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
2e2e0 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
2e2f0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
2e300 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  be invoked..** ^
2e310 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2e320 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
2e330 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
2e340 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
2e350 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
2e360 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
2e370 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2e380 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
2e390 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  * ^The final cal
2e3a0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
2e3b0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
2e3c0 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49  f the row..** ^I
2e3d0 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
2e3e0 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
2e3f0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74   the [rowid] aft
2e400 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61  er the update ta
2e410 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
2e420 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f   ^(The update ho
2e430 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
2e440 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
2e450 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
2e460 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
2e470 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
2e480 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
2e490 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  uence).)^.**.** 
2e4a0 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  ^In the current 
2e4b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
2e4c0 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
2e4d0 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ** is not invoke
2e4e0 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69  d when duplicati
2e4f0 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  on rows are dele
2e500 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61  ted because of a
2e510 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  n.** [ON CONFLIC
2e520 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  T | ON CONFLICT 
2e530 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e  REPLACE] clause.
2e540 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70    ^Nor is the up
2e550 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76  date hook.** inv
2e560 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61  oked when rows a
2e570 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  re deleted using
2e580 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f   the [truncate o
2e590 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a  ptimization]..**
2e5a0 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20   The exceptions 
2e5b0 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20  defined in this 
2e5c0 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20  paragraph might 
2e5d0 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
2e5e0 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
2e5f0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
2e600 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
2e610 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2e620 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
2e630 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
2e640 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
2e650 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
2e660 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
2e670 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e  update hook.  An
2e680 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
2e690 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2e6a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2e6b0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
2e6c0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
2e6d0 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
2e6e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2e6f0 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
2e700 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70  triggered the up
2e710 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f  date hook..** No
2e720 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
2e730 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2e740 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
2e750 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
2e760 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
2e770 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
2e780 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
2e790 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
2e7a0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
2e7b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e7c0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c  update_hook(D,C,
2e7d0 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  P) function.** r
2e7e0 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67  eturns the P arg
2e7f0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2e800 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20  revious call.** 
2e810 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2e820 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2e830 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
2e840 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
2e850 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53  ll on D..**.** S
2e860 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
2e870 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2e880 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2e890 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
2e8a0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ].** interfaces.
2e8b0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2e8c0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
2e8d0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2e8e0 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
2e8f0 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
2e900 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
2e910 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
2e920 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
2e930 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
2e940 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
2e950 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20   Pager Cache.** 
2e960 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
2e970 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e  d cache}.**.** ^
2e980 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
2e990 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
2e9a0 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
2e9b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
2e9c0 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
2e9d0 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
2e9e0 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
2e9f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
2ea00 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
2ea10 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
2ea20 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
2ea30 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
2ea40 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
2ea50 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
2ea60 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
2ea70 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
2ea80 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
2ea90 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
2eaa0 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
2eab0 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
2eac0 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
2ead0 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
2eae0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
2eaf0 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
2eb00 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
2eb10 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
2eb20 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
2eb30 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
2eb40 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
2eb50 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
2eb60 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
2eb70 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
2eb80 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
2eb90 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2eba0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
2ebb0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2ebc0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
2ebd0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2ebe0 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
2ebf0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2ec00 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
2ec10 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
2ec20 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
2ec30 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
2ec40 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
2ec50 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
2ec60 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
2ec70 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2ec80 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
2ec90 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
2eca0 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
2ecb0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
2ecc0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2ecd0 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
2ece0 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
2ecf0 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
2ed00 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
2ed10 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
2ed20 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
2ed30 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
2ed40 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
2ed50 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
2ed60 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
2ed70 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
2ed80 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
2ed90 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  licitly..**.** S
2eda0 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74  ee Also:  [SQLit
2edb0 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d  e Shared-Cache M
2edc0 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ode].*/.int sqli
2edd0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
2ede0 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
2edf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
2ee00 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
2ee10 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
2ee20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2ee30 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
2ee40 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2ee50 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
2ee60 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
2ee70 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
2ee80 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
2ee90 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
2eea0 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
2eeb0 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
2eec0 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
2eed0 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
2eee0 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
2eef0 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
2ef00 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
2ef10 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
2ef20 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
2ef30 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
2ef40 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
2ef50 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2ef60 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
2ef70 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
2ef80 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
2ef90 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
2efa0 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
2efb0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2efc0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
2efd0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2efe0 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69  REF: Impose A Li
2eff0 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
2f000 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f010 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2f020 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2f030 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20  places a "soft" 
2f040 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  limit.** on the 
2f050 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
2f060 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
2f070 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
2f080 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e  QLite..** ^If an
2f090 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61   internal alloca
2f0a0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
2f0b0 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63  d that would exc
2f0c0 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20  eed the.** soft 
2f0d0 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c  heap limit, [sql
2f0e0 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2f0f0 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ory()] is invoke
2f100 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65  d one or.** more
2f110 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75   times to free u
2f120 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66  p some space bef
2f130 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69  ore the allocati
2f140 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
2f150 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69  .**.** ^The limi
2f160 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66  t is called "sof
2f170 74 22 20 62 65 63 61 75 73 65 20 69 66 20 5b 73  t" because if [s
2f180 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2f190 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e  emory()].** cann
2f1a0 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65  ot free sufficie
2f1b0 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65  nt memory to pre
2f1c0 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66  vent the limit f
2f1d0 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64  rom being exceed
2f1e0 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  ed,.** the memor
2f1f0 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61  y is allocated a
2f200 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75  nyway and the cu
2f210 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrent operation 
2f220 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  proceeds..**.** 
2f230 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a  ^A negative or z
2f240 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20  ero value for N 
2f250 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
2f260 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70   is no soft heap
2f270 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73   limit and.** [s
2f280 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2f290 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
2f2a0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2f2b0 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61  n memory is exha
2f2c0 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  usted..** ^The d
2f2d0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
2f2e0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2f2f0 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
2f300 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b  .** ^(SQLite mak
2f310 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
2f320 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
2f330 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a  ft heap limit..*
2f340 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66  * But if the sof
2f350 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
2f360 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20  not be honored, 
2f370 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
2f380 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
2f390 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
2f3a0 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69  fication.)^  Thi
2f3b0 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
2f3c0 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20  it is.** called 
2f3d0 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
2f3e0 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
2f3f0 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
2f400 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
2f410 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
2f420 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
2f430 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
2f440 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
2f450 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
2f460 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
2f470 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
2f480 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
2f490 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
2f4a0 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
2f4b0 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
2f4c0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
2f4d0 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
2f4e0 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
2f4f0 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2f500 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2f510 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
2f520 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
2f530 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
2f540 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
2f550 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e   all threads. In
2f560 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
2f570 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
2f580 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
2f590 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
2f5a0 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
2f5b0 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
2f5c0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
2f5d0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
2f5e0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2f5f0 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65  3REF: Extract Me
2f600 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
2f610 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
2f620 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2f630 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74  tine returns met
2f640 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70  adata about a sp
2f650 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66  ecific column of
2f660 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64   a specific.** d
2f670 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63  atabase table ac
2f680 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74  cessible using t
2f690 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2f6a0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
2f6b0 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
2f6c0 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20   first function 
2f6d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2f6e0 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69  ^The column is i
2f6f0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2f700 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61   second, third a
2f710 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
2f720 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20  ters to.** this 
2f730 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73  function. ^The s
2f740 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2f750 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61  is either the na
2f760 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2f770 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69  se.** (i.e. "mai
2f780 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61  n", "temp", or a
2f790 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
2f7a0 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
2f7b0 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
2f7c0 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
2f7d0 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20  ^If it is NULL, 
2f7e0 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  then all attache
2f7f0 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20  d databases are 
2f800 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20  searched.** for 
2f810 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20  the table using 
2f820 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
2f830 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64  hm used by the d
2f840 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74  atabase engine t
2f850 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71  o.** resolve unq
2f860 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
2f870 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
2f880 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
2f890 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2f8a0 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
2f8b0 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65  on are the table
2f8c0 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e   and column.** n
2f8d0 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
2f8e0 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
2f8f0 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
2f900 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
2f910 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  ters.** may be N
2f920 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61  ULL..**.** ^Meta
2f930 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64  data is returned
2f940 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
2f950 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
2f960 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68  ons passed as th
2f970 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62  e 5th.** and sub
2f980 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
2f990 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
2f9a0 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65  ion. ^Any of the
2f9b0 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79  se arguments may
2f9c0 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20   be.** NULL, in 
2f9d0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
2f9e0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
2f9f0 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61  ment of metadata
2fa00 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a   is omitted..**.
2fa10 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65  ** ^(<blockquote
2fa20 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2fa30 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2fa40 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74  th> Parameter <t
2fa50 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70  h> Output<br>Typ
2fa60 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74  e <th>  Descript
2fa70 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2fa80 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 5th <td> cons
2fa90 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74  t char* <td> Dat
2faa0 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74  a type.** <tr><t
2fab0 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 6th <td> cons
2fac0 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d  t char* <td> Nam
2fad0 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c  e of default col
2fae0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a  lation sequence.
2faf0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20  ** <tr><td> 7th 
2fb00 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
2fb10 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
2fb20 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e  lumn has a NOT N
2fb30 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  ULL constraint.*
2fb40 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c  * <tr><td> 8th <
2fb50 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2fb60 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2fb70 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74  umn is part of t
2fb80 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a  he PRIMARY KEY.*
2fb90 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c  * <tr><td> 9th <
2fba0 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2fbb0 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2fbc0 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52  umn is [AUTOINCR
2fbd0 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c  EMENT].** </tabl
2fbe0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2fbf0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
2fc00 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20   memory pointed 
2fc10 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63  to by the charac
2fc20 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ter pointers ret
2fc30 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  urned for the.**
2fc40 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
2fc50 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
2fc60 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
2fc70 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
2fc80 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f   next.** call to
2fc90 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20   any SQLite API 
2fca0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2fcb0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
2fcc0 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
2fcd0 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b  lly a view, an [
2fce0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2fcf0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2fd00 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
2fd10 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69   column is "rowi
2fd20 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72  d", "oid" or "_r
2fd30 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a  owid_" and an.**
2fd40 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2fd50 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61  Y KEY] column ha
2fd60 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c  s been explicitl
2fd70 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e  y declared, then
2fd80 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2fd90 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2fda0 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63  t for the explic
2fdb0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
2fdc0 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65  lumn. ^(If there
2fdd0 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63   is no.** explic
2fde0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49  itly declared [I
2fdf0 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
2fe00 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e  EY] column, then
2fe10 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2fe20 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2fe30 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
2fe40 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
2fe50 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54   data type: "INT
2fe60 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c  EGER".**     col
2fe70 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a  lation sequence:
2fe80 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20   "BINARY".**    
2fe90 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20   not null: 0.** 
2fea0 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a      primary key:
2feb0 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69   1.**     auto i
2fec0 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c  ncrement: 0.** <
2fed0 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  /pre>)^.**.** ^(
2fee0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
2fef0 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f  y load one or mo
2ff00 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20  re schemas from 
2ff10 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20  database files. 
2ff20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f  If an.** error o
2ff30 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69  ccurs during thi
2ff40 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  s process, or if
2ff50 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74   the requested t
2ff60 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a  able or column.*
2ff70 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e  * cannot be foun
2ff80 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  d, an [error cod
2ff90 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
2ffa0 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  nd an error mess
2ffb0 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74  age left.** in t
2ffc0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2ffd0 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20  nection] (to be 
2ffe0 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20  retrieved using 
2fff0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
30000 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ).)^.**.** ^This
30010 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61   API is only ava
30020 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
30030 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
30040 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
30050 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
30060 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
30070 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
30080 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  mbol defined..*/
30090 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62  .int sqlite3_tab
300a0 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61  le_column_metada
300b0 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ta(.  sqlite3 *d
300c0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
300d0 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20    /* Connection 
300e0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
300f0 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
30100 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
30110 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c  ase name or NULL
30120 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
30130 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20   *zTableName,   
30140 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20    /* Table name 
30150 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
30160 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20  *zColumnName,   
30170 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20   /* Column name 
30180 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
30190 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20  **pzDataType,   
301a0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c   /* OUTPUT: Decl
301b0 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a  ared data type *
301c0 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
301d0 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20  *pzCollSeq,     
301e0 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61  /* OUTPUT: Colla
301f0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61  tion sequence na
30200 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f  me */.  int *pNo
30210 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20  tNull,          
30220 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
30230 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20  rue if NOT NULL 
30240 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74  constraint exist
30250 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69  s */.  int *pPri
30260 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20  maryKey,        
30270 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
30280 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72  ue if column par
30290 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74  t of PK */.  int
302a0 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20   *pAutoinc      
302b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
302c0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
302d0 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65  mn is auto-incre
302e0 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ment */.);../*.*
302f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
30300 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a   An Extension.**
30310 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
30320 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c  ace loads an SQL
30330 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
30340 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e  brary from the n
30350 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  amed file..**.**
30360 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
30370 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
30380 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
30390 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20  s to load an.** 
303a0 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
303b0 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
303c0 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a  ed in the file z
303d0 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  File..**.** ^The
303e0 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
303f0 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63  zProc..** ^zProc
30400 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68   may be 0, in wh
30410 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d  ich case the nam
30420 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70  e of the entry p
30430 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73  oint.** defaults
30440 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74   to "sqlite3_ext
30450 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a  ension_init"..**
30460 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
30470 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
30480 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30490 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
304a0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b  on success and [
304b0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
304c0 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20   something goes 
304d0 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e  wrong..** ^If an
304e0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e   error occurs an
304f0 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f  d pzErrMsg is no
30500 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  t 0, then the.**
30510 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
30520 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
30530 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65  rface shall atte
30540 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a  mpt to.** fill *
30550 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72  pzErrMsg with er
30560 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
30570 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72   stored in memor
30580 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72  y.** obtained fr
30590 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
305a0 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69  oc()]. The calli
305b0 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  ng function.** s
305c0 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20  hould free this 
305d0 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e  memory by callin
305e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  g [sqlite3_free(
305f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e  )]..**.** ^Exten
30600 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73  sion loading mus
30610 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69  t be enabled usi
30620 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
30630 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
30640 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f  sion()] prior to
30650 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50   calling this AP
30660 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  I,.** otherwise 
30670 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  an error will be
30680 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
30690 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c   See also the [l
306a0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
306b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
306c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f  /.int sqlite3_lo
306d0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20  ad_extension(.  
306e0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
306f0 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68        /* Load th
30700 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f  e extension into
30710 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63   this database c
30720 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63  onnection */.  c
30730 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
30740 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20  ,    /* Name of 
30750 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61  the shared libra
30760 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78  ry containing ex
30770 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  tension */.  con
30780 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20  st char *zProc, 
30790 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e     /* Entry poin
307a0 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d  t.  Derived from
307b0 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20   zFile if 0 */. 
307c0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67   char **pzErrMsg
307d0 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72         /* Put er
307e0 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65  ror message here
307f0 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a   if not 0 */.);.
30800 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30810 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
30820 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  le Extension Loa
30830 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61  ding.**.** ^So a
30840 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65  s not to open se
30850 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20  curity holes in 
30860 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f  older applicatio
30870 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75  ns that are.** u
30880 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61  nprepared to dea
30890 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e  l with extension
308a0 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73   loading, and as
308b0 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61   a means of disa
308c0 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69  bling.** extensi
308d0 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65  on loading while
308e0 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72   evaluating user
308f0 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68  -entered SQL, th
30900 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a  e following API.
30910 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  ** is provided t
30920 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  o turn the [sqli
30930 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
30940 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20  on()] mechanism 
30950 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a  on and off..**.*
30960 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  * ^Extension loa
30970 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64  ding is off by d
30980 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b  efault. See tick
30990 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61  et #1863..** ^Ca
309a0 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  ll the sqlite3_e
309b0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
309c0 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77  sion() routine w
309d0 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20  ith onoff==1.** 
309e0 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f  to turn extensio
309f0 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64  n loading on and
30a00 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e   call it with on
30a10 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a  off==0 to turn.*
30a20 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67  * it back off ag
30a30 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ain..*/.int sqli
30a40 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
30a50 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65  extension(sqlite
30a60 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66  3 *db, int onoff
30a70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30a80 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c  EF: Automaticall
30a90 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  y Load An Extens
30aa0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ions.**.** ^This
30ab0 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f   API can be invo
30ac0 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73  ked at program s
30ad0 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20  tartup in order 
30ae0 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f  to register.** o
30af0 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69  ne or more stati
30b00 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74  cally linked ext
30b10 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c  ensions that wil
30b20 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a  l be available.*
30b30 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61  * to all new [da
30b40 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30b50 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ns]..**.** ^(Thi
30b60 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
30b70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
30b80 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72  e extension entr
30b90 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e  y point.** in an
30ba0 20 61 72 72 61 79 20 74 68 61 74 20 69 73 20 6f   array that is o
30bb0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
30bc0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
30bd0 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a    That memory.**
30be0 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   is deallocated 
30bf0 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  by [sqlite3_rese
30c00 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
30c10 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
30c20 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  is function regi
30c30 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69  sters an extensi
30c40 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74  on entry point t
30c50 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  hat is.** automa
30c60 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20  tically invoked 
30c70 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b  whenever a new [
30c80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30c90 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65  ion].** is opene
30ca0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
30cb0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
30cc0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
30cd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
30ce0 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70  n_v2()]..** ^Dup
30cf0 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e  licate extension
30d00 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73  s are detected s
30d10 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  o calling this r
30d20 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70  outine.** multip
30d30 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  le times with th
30d40 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e  e same extension
30d50 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a   is harmless..**
30d60 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65   ^Automatic exte
30d70 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72  nsions apply acr
30d80 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  oss all threads.
30d90 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30da0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
30db0 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e  oid (*xEntryPoin
30dc0 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a  t)(void));../*.*
30dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
30de0 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65  t Automatic Exte
30df0 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
30e00 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74  .** ^(This funct
30e10 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c  ion disables all
30e20 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
30e30 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63  stered automatic
30e40 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20  .** extensions. 
30e50 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  It undoes the ef
30e60 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
30e70 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75  r.** [sqlite3_au
30e80 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  to_extension()] 
30e90 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  calls.)^.**.** ^
30ea0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69  This function di
30eb0 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63  sables automatic
30ec0 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61   extensions in a
30ed0 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  ll threads..*/.v
30ee0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
30ef0 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
30f00 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  (void);../*.** T
30f10 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
30f20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
30f30 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63  e mechanism is c
30f40 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
30f50 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
30f60 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
30f70 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
30f80 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
30f90 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
30fa0 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
30fb0 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
30fc0 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
30fd0 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
30fe0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
30ff0 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
31000 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
31010 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
31020 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
31030 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
31040 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
31050 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
31060 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
31070 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75  ..*/../*.** Stru
31080 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74  ctures used by t
31090 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
310a0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79   interface.*/.ty
310b0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
310c0 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65  ite3_vtab sqlite
310d0 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20  3_vtab;.typedef 
310e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
310f0 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65  ndex_info sqlite
31100 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79  3_index_info;.ty
31110 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
31120 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
31130 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
31140 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74  rsor;.typedef st
31150 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
31160 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ule sqlite3_modu
31170 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  le;../*.** CAPI3
31180 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
31190 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  le Object.** KEY
311a0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d  WORDS: sqlite3_m
311b0 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74  odule {virtual t
311c0 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a  able module}.**.
311d0 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
311e0 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c  e, sometimes cal
311f0 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 61 6c  led a a "virtual
31200 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20   table module", 
31210 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20  .** defines the 
31220 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
31230 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  f a [virtual tab
31240 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20  les].  .** This 
31250 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73  structure consis
31260 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74  ts mostly of met
31270 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
31280 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69  ule..**.** ^A vi
31290 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
312a0 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79  le is created by
312b0 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65   filling in a pe
312c0 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74  rsistent.** inst
312d0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
312e0 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69  ucture and passi
312f0 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ng a pointer to 
31300 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a  that instance.**
31310 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
31320 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72  ate_module()] or
31330 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31340 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a  _module_v2()]..*
31350 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72 61 74  * ^The registrat
31360 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69  ion remains vali
31370 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65  d until it is re
31380 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66  placed by a diff
31390 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20  erent.** module 
313a0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61  or until the [da
313b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
313c0 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20  n] closes.  The 
313d0 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  content.** of th
313e0 69 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  is structure mus
313f0 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69  t not change whi
31400 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65  le it is registe
31410 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20  red with.** any 
31420 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31430 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ion..*/.struct s
31440 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a  qlite3_module {.
31450 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
31460 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29    int (*xCreate)
31470 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
31480 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
31490 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
314a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
314b0 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
314c0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
314d0 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
314e0 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
314f0 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  Connect)(sqlite3
31500 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
31510 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
31520 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
31530 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
31540 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
31550 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
31560 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
31570 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65   int (*xBestInde
31580 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  x)(sqlite3_vtab 
31590 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
315a0 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20  index_info*);.  
315b0 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63  int (*xDisconnec
315c0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
315d0 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
315e0 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74  *xDestroy)(sqlit
315f0 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
31600 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
31610 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
31620 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61  Tab, sqlite3_vta
31630 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72  b_cursor **ppCur
31640 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sor);.  int (*xC
31650 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74  lose)(sqlite3_vt
31660 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
31670 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71  nt (*xFilter)(sq
31680 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
31690 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20  r*, int idxNum, 
316a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53  const char *idxS
316b0 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  tr,.            
316c0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71      int argc, sq
316d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72  lite3_value **ar
316e0 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65  gv);.  int (*xNe
316f0 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  xt)(sqlite3_vtab
31700 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
31710 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33   (*xEof)(sqlite3
31720 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
31730 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29    int (*xColumn)
31740 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
31750 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63  rsor*, sqlite3_c
31760 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20  ontext*, int);. 
31770 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73   int (*xRowid)(s
31780 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
31790 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  or*, sqlite3_int
317a0 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69  64 *pRowid);.  i
317b0 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71  nt (*xUpdate)(sq
317c0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e  lite3_vtab *, in
317d0 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  t, sqlite3_value
317e0 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74   **, sqlite3_int
317f0 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  64 *);.  int (*x
31800 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76  Begin)(sqlite3_v
31810 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
31820 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
31830 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
31840 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69  ;.  int (*xCommi
31850 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
31860 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
31870 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69  *xRollback)(sqli
31880 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
31890 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46  ;.  int (*xFindF
318a0 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33  unction)(sqlite3
318b0 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e  _vtab *pVtab, in
318c0 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68  t nArg, const ch
318d0 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20  ar *zName,.     
318e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
318f0 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63    void (**pxFunc
31900 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31910 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
31920 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20  alue**),.       
31930 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31940 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20  void **ppArg);. 
31950 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28   int (*xRename)(
31960 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
31970 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  tab, const char 
31980 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  *zNew);.};../*.*
31990 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
319a0 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69  ual Table Indexi
319b0 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ng Information.*
319c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
319d0 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a  te3_index_info.*
319e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
319f0 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
31a00 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
31a10 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
31a20 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20 6f  sed as part.** o
31a30 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
31a40 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65 20  able] interface 
31a50 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f 72  to.** pass infor
31a60 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64 20  mation into and 
31a70 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70 6c  receive the repl
31a80 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65 73  y from the [xBes
31a90 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68 6f  tIndex].** metho
31aa0 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20  d of a [virtual 
31ab0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
31ac0 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65 72  The fields under
31ad0 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65 20   **Inputs** are 
31ae0 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74 6f  the.** inputs to
31af0 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64 20   xBestIndex and 
31b00 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20 20  are read-only.  
31b10 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65 72  xBestIndex inser
31b20 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c 74  ts its.** result
31b30 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75 74  s into the **Out
31b40 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a 2a  puts** fields..*
31b50 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e 73  *.** ^(The aCons
31b60 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20 72  traint[] array r
31b70 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c 61  ecords WHERE cla
31b80 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  use constraints 
31b90 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a 0a  of the form:.**.
31ba0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 63  ** <blockquote>c
31bb0 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 62  olumn OP expr</b
31bc0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
31bd0 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c 20   where OP is =, 
31be0 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67 74  &lt;, &lt;=, &gt
31bf0 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20 20  ;, or &gt;=.)^  
31c00 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61 72  ^(The particular
31c10 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a 20   operator is.** 
31c20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73 74  stored in aConst
31c30 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e 67  raint[].op using
31c40 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b   one of the.** [
31c50 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
31c60 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51 4c  STRAINT_EQ | SQL
31c70 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
31c80 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29 5e  AINT_ values].)^
31c90 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78 20  .** ^(The index 
31ca0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73  of the column is
31cb0 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61 43   stored in.** aC
31cc0 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f 6c  onstraint[].iCol
31cd0 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73 74  umn.)^  ^(aConst
31ce0 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20 69  raint[].usable i
31cf0 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a 2a  s TRUE if the.**
31d00 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69 67   expr on the rig
31d10 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61 6e  ht-hand side can
31d20 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28 61   be evaluated (a
31d30 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e 73  nd thus the cons
31d40 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73 61  traint.** is usa
31d50 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20 69  ble) and false i
31d60 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a 2a  f it cannot.)^.*
31d70 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d 69  *.** ^The optimi
31d80 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  zer automaticall
31d90 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73 20  y inverts terms 
31da0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78 70  of the form "exp
31db0 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a 20  r OP column".** 
31dc0 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72 20  and makes other 
31dd0 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73 20  simplifications 
31de0 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c 61  to the WHERE cla
31df0 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d 70  use in an attemp
31e00 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20 6d  t to.** get as m
31e10 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73 65  any WHERE clause
31e20 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65 20   terms into the 
31e30 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76 65  form shown above
31e40 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a   as possible..**
31e50 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e   ^The aConstrain
31e60 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20 72  t[] array only r
31e70 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c 61  eports WHERE cla
31e80 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20 61  use terms that a
31e90 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20 74  re.** relevant t
31ea0 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  o the particular
31eb0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 62   virtual table b
31ec0 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a 2a  eing queried..**
31ed0 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f 6e  .** ^Information
31ee0 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45 52   about the ORDER
31ef0 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73 74   BY clause is st
31f00 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42 79  ored in aOrderBy
31f10 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65 72  []..** ^Each ter
31f20 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72 65  m of aOrderBy re
31f30 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  cords a column o
31f40 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  f the ORDER BY c
31f50 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  lause..**.** The
31f60 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d 65   [xBestIndex] me
31f70 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20 61  thod must fill a
31f80 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b  ConstraintUsage[
31f90 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74 69  ] with informati
31fa0 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61 74  on.** about what
31fb0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 70   parameters to p
31fc0 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e 20  ass to xFilter. 
31fd0 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e 30   ^If argvIndex>0
31fe0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69 67   then.** the rig
31ff0 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ht-hand side of 
32000 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
32010 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20  g aConstraint[] 
32020 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a 20  is evaluated.** 
32030 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65 20  and becomes the 
32040 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e 74  argvIndex-th ent
32050 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28 49  ry in argv.  ^(I
32060 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61  f aConstraintUsa
32070 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73 20  ge[].omit.** is 
32080 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20 63  true, then the c
32090 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73 73  onstraint is ass
320a0 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c 79  umed to be fully
320b0 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65 0a   handled by the.
320c0 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ** virtual table
320d0 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65 63   and is not chec
320e0 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51 4c  ked again by SQL
320f0 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ite.)^.**.** ^Th
32100 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64 78  e idxNum and idx
32110 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20 72  Ptr values are r
32120 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73 73  ecorded and pass
32130 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b  ed into the.** [
32140 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64 2e  xFilter] method.
32150 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66 72  .** ^[sqlite3_fr
32160 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  ee()] is used to
32170 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66 20   free idxPtr if 
32180 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 6e  and only if.** n
32190 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72 20  eedToFreeIdxPtr 
321a0 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e  is true..**.** ^
321b0 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  The orderByConsu
321c0 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20 6f  med means that o
321d0 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69 6c  utput from [xFil
321e0 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69 6c  ter]/[xNext] wil
321f0 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74 68  l occur in.** th
32200 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72 20  e correct order 
32210 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20 4f  to satisfy the O
32220 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 73  RDER BY clause s
32230 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72 61  o that no separa
32240 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73 74  te.** sorting st
32250 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a  ep is required..
32260 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69 6d  **.** ^The estim
32270 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20 69  atedCost value i
32280 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  s an estimate of
32290 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f 69   the cost of doi
322a0 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69 63  ng the.** partic
322b0 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41 20  ular lookup.  A 
322c0 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20 74  full scan of a t
322d0 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74 72  able with N entr
322e0 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 0a  ies should have.
322f0 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e 20  ** a cost of N. 
32300 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63 68   A binary search
32310 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20 4e   of a table of N
32320 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64 20   entries should 
32330 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20 6f  have a.** cost o
32340 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20  f approximately 
32350 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75 63  log(N)..*/.struc
32360 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
32370 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70 75  info {.  /* Inpu
32380 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f 6e  ts */.  int nCon
32390 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20  straint;        
323a0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
323b0 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e 73  entries in aCons
323c0 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72 75  traint */.  stru
323d0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
323e0 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20 20  _constraint {.  
323f0 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20     int iColumn; 
32400 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
32410 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d 68  Column on left-h
32420 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e 73  and side of cons
32430 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20 75  traint */.     u
32440 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70 3b  nsigned char op;
32450 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 73           /* Cons
32460 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72 20  traint operator 
32470 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
32480 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20 20   char usable;   
32490 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68 69    /* True if thi
324a0 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  s constraint is 
324b0 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20 69  usable */.     i
324c0 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b 20  nt iTermOffset; 
324d0 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65 64           /* Used
324e0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78 42   internally - xB
324f0 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64 20  estIndex should 
32500 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a 61  ignore */.  } *a
32510 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20  Constraint;     
32520 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65 20         /* Table 
32530 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  of WHERE clause 
32540 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a 20  constraints */. 
32550 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20 20   int nOrderBy;  
32560 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
32570 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
32580 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  n the ORDER BY c
32590 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75 63  lause */.  struc
325a0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
325b0 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20 69  orderby {.     i
325c0 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20  nt iColumn;     
325d0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75           /* Colu
325e0 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20 20  mn number */.   
325f0 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
32600 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20 54  desc;       /* T
32610 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20 46  rue for DESC.  F
32620 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a 2f  alse for ASC. */
32630 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b 20  .  } *aOrderBy; 
32640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
32650 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   The ORDER BY cl
32660 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75 74  ause */.  /* Out
32670 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63 74  puts */.  struct
32680 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63   sqlite3_index_c
32690 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65 20  onstraint_usage 
326a0 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49 6e  {.    int argvIn
326b0 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20 2f  dex;           /
326c0 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72 61  * if >0, constra
326d0 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20 61  int is part of a
326e0 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20 2a  rgv to xFilter *
326f0 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63  /.    unsigned c
32700 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20 2f  har omit;      /
32710 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61 20  * Do not code a 
32720 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63 6f  test for this co
32730 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d 20  nstraint */.  } 
32740 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67  *aConstraintUsag
32750 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d 3b  e;.  int idxNum;
32760 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32770 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20 74  /* Number used t
32780 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20 69  o identify the i
32790 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ndex */.  char *
327a0 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20 20  idxStr;         
327b0 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c 20       /* String, 
327c0 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e 65  possibly obtaine
327d0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
327e0 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20 6e  alloc */.  int n
327f0 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72 3b  eedToFreeIdxStr;
32800 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69 64        /* Free id
32810 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69 74  xStr using sqlit
32820 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72 75  e3_free() if tru
32830 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65 72  e */.  int order
32840 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20 20  ByConsumed;     
32850 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75 74    /* True if out
32860 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20 6f  put is already o
32870 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75 62  rdered */.  doub
32880 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73 74  le estimatedCost
32890 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d 61  ;      /* Estima
328a0 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69 6e  ted cost of usin
328b0 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f 0a  g this index */.
328c0 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
328d0 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
328e0 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70 65  e Constraint Ope
328f0 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a 2a  rator Codes.**.*
32900 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 64  * These macros d
32910 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f 77  efined the allow
32920 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  ed values for th
32930 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  e.** [sqlite3_in
32940 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73 74  dex_info].aConst
32950 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c 64  raint[].op field
32960 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20 72 65  .  Each value re
32970 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20 6f  presents.** an o
32980 70 65 72 61 74 6f 72 20 74 68 61 74 20 69 73 20  perator that is 
32990 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74 72  part of a constr
329a0 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68 65  aint term in the
329b0 20 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f 66   wHERE clause of
329c0 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61 74  .** a query that
329d0 20 75 73 65 73 20 61 20 5b 76 69 72 74 75 61 6c   uses a [virtual
329e0 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65 66   table]..*/.#def
329f0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
32a00 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20 20  _CONSTRAINT_EQ  
32a10 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
32a20 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
32a30 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65 66  INT_GT    4.#def
32a40 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
32a50 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20 20  _CONSTRAINT_LE  
32a60 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
32a70 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
32a80 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64 65  INT_LT    16.#de
32a90 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
32aa0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45 20  X_CONSTRAINT_GE 
32ab0 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53 51     32.#define SQ
32ac0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
32ad0 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a 0a  RAINT_MATCH 64..
32ae0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32af0 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74 75  Register A Virtu
32b00 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d 65  al Table Impleme
32b10 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  ntation.**.** ^T
32b20 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
32b30 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73 74  e used to regist
32b40 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75 61  er a new [virtua
32b50 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
32b60 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c 65  name..** ^Module
32b70 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20 72   names must be r
32b80 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72 65  egistered before
32b90 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20 6e  .** creating a n
32ba0 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ew [virtual tabl
32bb0 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f 64  e] using the mod
32bc0 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20 75  ule and before u
32bd0 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78 69  sing a.** preexi
32be0 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20 74  sting [virtual t
32bf0 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  able] for the mo
32c00 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dule..**.** ^The
32c10 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73 20   module name is 
32c20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74 68  registered on th
32c30 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
32c40 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
32c50 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
32c60 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  t parameter.  ^T
32c70 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
32c80 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20 62  odule is given b
32c90 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e 64  y the .** second
32ca0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
32cb0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
32cc0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
32cd0 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65  o.** the impleme
32ce0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  ntation of the [
32cf0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
32d00 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66 6f  dule].   ^The fo
32d10 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74 65  urth.** paramete
32d20 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
32d30 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70 6f  y client data po
32d40 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61  inter that is pa
32d50 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a 20  ssed through.** 
32d60 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61 74  into the [xCreat
32d70 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74  e] and [xConnect
32d80 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65  ] methods of the
32d90 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
32da0 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61 20  odule.** when a 
32db0 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62 6c  new virtual tabl
32dc0 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63 72  e is be being cr
32dd0 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74 69  eated or reiniti
32de0 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  alized..**.** ^T
32df0 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
32e00 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69 6e  e_module_v2() in
32e10 74 65 72 66 61 63 65 20 68 61 73 20 61 20 66 69  terface has a fi
32e20 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 77 68  fth parameter wh
32e30 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
32e40 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63  ter to a destruc
32e50 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c 69  tor for the pCli
32e60 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69 74  entData.  ^SQLit
32e70 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b 65  e will.** invoke
32e80 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
32e90 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74 20  function (if it 
32ea0 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68 65  is not NULL) whe
32eb0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20 6c  n SQLite.** no l
32ec0 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65 20  onger needs the 
32ed0 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69 6e  pClientData poin
32ee0 74 65 72 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ter.  ^The sqlit
32ef0 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
32f00 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
32f10 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
32f20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32f30 6d 6f 64 75 6c 65 5f 76 32 28 29 20 77 69 74 68  module_v2() with
32f40 20 61 20 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72   a NULL.** destr
32f50 75 63 74 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  uctor..*/.int sq
32f60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
32f70 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ule(.  sqlite3 *
32f80 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
32f90 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e    /* SQLite conn
32fa0 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74  ection to regist
32fb0 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a  er module with *
32fc0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
32fd0 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f  zName,         /
32fe0 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f  * Name of the mo
32ff0 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  dule */.  const 
33000 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a  sqlite3_module *
33010 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  p,   /* Methods 
33020 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a  for the module *
33030 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e  /.  void *pClien
33040 74 44 61 74 61 20 20 20 20 20 20 20 20 20 20 2f  tData          /
33050 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f  * Client data fo
33060 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65  r xCreate/xConne
33070 63 74 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ct */.);.int sql
33080 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
33090 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  le_v2(.  sqlite3
330a0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
330b0 20 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f      /* SQLite co
330c0 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69  nnection to regi
330d0 73 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68  ster module with
330e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
330f0 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20   *zName,        
33100 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20   /* Name of the 
33110 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  module */.  cons
33120 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
33130 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64   *p,   /* Method
33140 73 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65  s for the module
33150 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69   */.  void *pCli
33160 65 6e 74 44 61 74 61 2c 20 20 20 20 20 20 20 20  entData,        
33170 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20   /* Client data 
33180 66 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e  for xCreate/xCon
33190 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69 64 28 2a  nect */.  void(*
331a0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
331b0 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c 65 20 64       /* Module d
331c0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
331d0 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  on */.);../*.** 
331e0 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
331f0 6c 20 54 61 62 6c 65 20 49 6e 73 74 61 6e 63 65  l Table Instance
33200 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
33210 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
33220 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76  b.**.** Every [v
33230 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
33240 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ule] implementat
33250 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c  ion uses a subcl
33260 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69 73 20 6f  ass.** of this o
33270 62 6a 65 63 74 20 74 6f 20 64 65 73 63 72 69 62  bject to describ
33280 65 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 69  e a particular i
33290 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66 20 74 68  nstance.** of th
332a0 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  e [virtual table
332b0 5d 2e 20 20 45 61 63 68 20 73 75 62 63 6c 61 73  ].  Each subclas
332c0 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 74 61 69  s will.** be tai
332d0 6c 6f 72 65 64 20 74 6f 20 74 68 65 20 73 70 65  lored to the spe
332e0 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 20 74  cific needs of t
332f0 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d  he module implem
33300 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  entation..** The
33310 20 70 75 72 70 6f 73 65 20 6f 66 20 74 68 69 73   purpose of this
33320 20 73 75 70 65 72 63 6c 61 73 73 20 69 73 20 74   superclass is t
33330 6f 20 64 65 66 69 6e 65 20 63 65 72 74 61 69 6e  o define certain
33340 20 66 69 65 6c 64 73 20 74 68 61 74 20 61 72 65   fields that are
33350 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c  .** common to al
33360 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65  l module impleme
33370 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  ntations..**.** 
33380 5e 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20  ^Virtual tables 
33390 6d 65 74 68 6f 64 73 20 63 61 6e 20 73 65 74 20  methods can set 
333a0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
333b0 20 62 79 20 61 73 73 69 67 6e 69 6e 67 20 61 0a   by assigning a.
333c0 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  ** string obtain
333d0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
333e0 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 7a  _mprintf()] to z
333f0 45 72 72 4d 73 67 2e 20 20 54 68 65 20 6d 65 74  ErrMsg.  The met
33400 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 74 61  hod should.** ta
33410 6b 65 20 63 61 72 65 20 74 68 61 74 20 61 6e 79  ke care that any
33420 20 70 72 69 6f 72 20 73 74 72 69 6e 67 20 69 73   prior string is
33430 20 66 72 65 65 64 20 62 79 20 61 20 63 61 6c 6c   freed by a call
33440 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
33450 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  e()].** prior to
33460 20 61 73 73 69 67 6e 69 6e 67 20 61 20 6e 65 77   assigning a new
33470 20 73 74 72 69 6e 67 20 74 6f 20 7a 45 72 72 4d   string to zErrM
33480 73 67 2e 20 20 5e 41 66 74 65 72 20 74 68 65 20  sg.  ^After the 
33490 65 72 72 6f 72 20 6d 65 73 73 61 67 65 0a 2a 2a  error message.**
334a0 20 69 73 20 64 65 6c 69 76 65 72 65 64 20 75 70   is delivered up
334b0 20 74 6f 20 74 68 65 20 63 6c 69 65 6e 74 20 61   to the client a
334c0 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
334d0 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 61  string will be a
334e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
334f0 66 72 65 65 64 20 62 79 20 73 71 6c 69 74 65 33  freed by sqlite3
33500 5f 66 72 65 65 28 29 20 61 6e 64 20 74 68 65 20  _free() and the 
33510 7a 45 72 72 4d 73 67 20 66 69 65 6c 64 20 77 69  zErrMsg field wi
33520 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f  ll be zeroed..*/
33530 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
33540 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73 74 20 73  vtab {.  const s
33550 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70  qlite3_module *p
33560 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54 68 65 20  Module;  /* The 
33570 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68 69 73 20  module for this 
33580 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 2a 2f  virtual table */
33590 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20 20 20 20  .  int nRef;    
335a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
335b0 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20     /* NO LONGER 
335c0 55 53 45 44 20 2a 2f 0a 20 20 63 68 61 72 20 2a  USED */.  char *
335d0 7a 45 72 72 4d 73 67 3b 20 20 20 20 20 20 20 20  zErrMsg;        
335e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
335f0 6f 72 20 6d 65 73 73 61 67 65 20 66 72 6f 6d 20  or message from 
33600 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
33610 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61  ) */.  /* Virtua
33620 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  l table implemen
33630 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70  tations will typ
33640 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74  ically add addit
33650 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a  ional fields */.
33660 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
33670 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c  EF: Virtual Tabl
33680 65 20 43 75 72 73 6f 72 20 4f 62 6a 65 63 74 0a  e Cursor Object.
33690 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
336a0 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
336b0 20 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   {virtual table 
336c0 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a 20 45 76  cursor}.**.** Ev
336d0 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62  ery [virtual tab
336e0 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65  le module] imple
336f0 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
33700 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
33710 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  .** following st
33720 72 75 63 74 75 72 65 20 74 6f 20 64 65 73 63 72  ructure to descr
33730 69 62 65 20 63 75 72 73 6f 72 73 20 74 68 61 74  ibe cursors that
33740 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74 68 65 0a   point into the.
33750 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
33760 65 5d 20 61 6e 64 20 61 72 65 20 75 73 65 64 0a  e] and are used.
33770 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68 72 6f 75  ** to loop throu
33780 67 68 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  gh the virtual t
33790 61 62 6c 65 2e 20 20 43 75 72 73 6f 72 73 20 61  able.  Cursors a
337a0 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
337b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
337c0 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e 20 7c 20  _module.xOpen | 
337d0 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 6f 66  xOpen] method of
337e0 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20   the module and 
337f0 61 72 65 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a  are destroyed.**
33800 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
33810 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73 65 20 7c  _module.xClose |
33820 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68 6f 64 2e   xClose] method.
33830 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 75 73    Cursors are us
33840 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 78 46  ed.** by the [xF
33850 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c  ilter], [xNext],
33860 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d   [xEof], [xColum
33870 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77 69 64 5d  n], and [xRowid]
33880 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 74   methods.** of t
33890 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45 61 63 68  he module.  Each
338a0 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e   module implemen
338b0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64 65 66 69  tation will defi
338c0 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  ne.** the conten
338d0 74 20 6f 66 20 61 20 63 75 72 73 6f 72 20 73 74  t of a cursor st
338e0 72 75 63 74 75 72 65 20 74 6f 20 73 75 69 74 20  ructure to suit 
338f0 69 74 73 20 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a  its own needs..*
33900 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70 65 72 63  *.** This superc
33910 6c 61 73 73 20 65 78 69 73 74 73 20 69 6e 20 6f  lass exists in o
33920 72 64 65 72 20 74 6f 20 64 65 66 69 6e 65 20 66  rder to define f
33930 69 65 6c 64 73 20 6f 66 20 74 68 65 20 63 75 72  ields of the cur
33940 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  sor that.** are 
33950 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d  common to all im
33960 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a  plementations..*
33970 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
33980 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 0a 20  _vtab_cursor {. 
33990 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70   sqlite3_vtab *p
339a0 56 74 61 62 3b 20 20 20 20 20 20 2f 2a 20 56 69  Vtab;      /* Vi
339b0 72 74 75 61 6c 20 74 61 62 6c 65 20 6f 66 20 74  rtual table of t
339c0 68 69 73 20 63 75 72 73 6f 72 20 2a 2f 0a 20 20  his cursor */.  
339d0 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
339e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
339f0 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20   will typically 
33a00 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  add additional f
33a10 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  ields */.};../*.
33a20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
33a30 6c 61 72 65 20 54 68 65 20 53 63 68 65 6d 61 20  lare The Schema 
33a40 4f 66 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  Of A Virtual Tab
33a50 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78  le.**.** ^The [x
33a60 43 72 65 61 74 65 5d 20 61 6e 64 20 5b 78 43 6f  Create] and [xCo
33a70 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64 73 20 6f  nnect] methods o
33a80 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  f a.** [virtual 
33a90 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 63 61  table module] ca
33aa0 6c 6c 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ll this interfac
33ab0 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61 72 65 20  e.** to declare 
33ac0 74 68 65 20 66 6f 72 6d 61 74 20 28 74 68 65 20  the format (the 
33ad0 6e 61 6d 65 73 20 61 6e 64 20 64 61 74 61 74 79  names and dataty
33ae0 70 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  pes of the colum
33af0 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65 20 76 69  ns) of.** the vi
33b00 72 74 75 61 6c 20 74 61 62 6c 65 73 20 74 68 65  rtual tables the
33b10 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a  y implement..*/.
33b20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c  int sqlite3_decl
33b30 61 72 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33  are_vtab(sqlite3
33b40 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
33b50 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  SQL);../*.** CAP
33b60 49 33 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20  I3REF: Overload 
33b70 41 20 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41  A Function For A
33b80 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a   Virtual Table.*
33b90 2a 0a 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74  *.** ^(Virtual t
33ba0 61 62 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64  ables can provid
33bb0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d  e alternative im
33bc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
33bd0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73   functions.** us
33be0 69 6e 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75  ing the [xFindFu
33bf0 6e 63 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f  nction] method o
33c00 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74  f the [virtual t
33c10 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a  able module].  .
33c20 2a 2a 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65  ** But global ve
33c30 72 73 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20  rsions of those 
33c40 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73  functions.** mus
33c50 74 20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72  t exist in order
33c60 20 74 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65   to be overloade
33c70 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  d.)^.**.** ^(Thi
33c80 73 20 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65  s API makes sure
33c90 20 61 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f   a global versio
33ca0 6e 20 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20  n of a function 
33cb0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
33cc0 72 0a 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75  r.** name and nu
33cd0 6d 62 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65  mber of paramete
33ce0 72 73 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e  rs exists.  If n
33cf0 6f 20 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20  o such function 
33d00 65 78 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65  exists.** before
33d10 20 74 68 69 73 20 41 50 49 20 69 73 20 63 61 6c   this API is cal
33d20 6c 65 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74  led, a new funct
33d30 69 6f 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29  ion is created.)
33d40 5e 20 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e  ^  ^The implemen
33d50 74 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65  tation.** of the
33d60 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c   new function al
33d70 77 61 79 73 20 63 61 75 73 65 73 20 61 6e 20 65  ways causes an e
33d80 78 63 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74  xception to be t
33d90 68 72 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68  hrown.  So.** th
33da0 65 20 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69  e new function i
33db0 73 20 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61  s not good for a
33dc0 6e 79 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c  nything by itsel
33dd0 66 2e 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20  f.  Its only.** 
33de0 70 75 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65  purpose is to be
33df0 20 61 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66   a placeholder f
33e00 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e  unction that can
33e10 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a   be overloaded.*
33e20 2a 20 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20  * by a [virtual 
33e30 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  table]..*/.int s
33e40 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61 64 5f  qlite3_overload_
33e50 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74 65 33  function(sqlite3
33e60 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
33e70 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20 6e 41  FuncName, int nA
33e80 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  rg);../*.** The 
33e90 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
33ea0 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
33eb0 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e 65 64  echanism defined
33ec0 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75 70 0a   above (back up.
33ed0 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e 74 20  ** to a comment 
33ee0 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d 69 6c  remarkably simil
33ef0 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65 29 20  ar to this one) 
33f00 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e  is currently con
33f10 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65  sidered.** to be
33f20 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20   experimental.  
33f30 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69  The interface mi
33f40 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e  ght change in in
33f50 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e  compatible ways.
33f60 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61  .** If this is a
33f70 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75   problem for you
33f80 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65  , do not use the
33f90 20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68   interface at th
33fa0 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57  is time..**.** W
33fb0 68 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d  hen the virtual-
33fc0 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20  table mechanism 
33fd0 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77  stabilizes, we w
33fe0 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a  ill declare the.
33ff0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78  ** interface fix
34000 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69  ed, support it i
34010 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64  ndefinitely, and
34020 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d   remove this com
34030 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  ment..*/../*.** 
34040 43 41 50 49 33 52 45 46 3a 20 41 20 48 61 6e 64  CAPI3REF: A Hand
34050 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20 42 4c  le To An Open BL
34060 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  OB.** KEYWORDS: 
34070 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20 7b 42  {BLOB handle} {B
34080 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a 2a 0a  LOB handles}.**.
34090 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
340a0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
340b0 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
340c0 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68 0a 2a   BLOB on which.*
340d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
340e0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
340f0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63 61 6e  al BLOB I/O] can
34100 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e 0a 2a   be performed..*
34110 2a 20 5e 4f 62 6a 65 63 74 73 20 6f 66 20 74 68  * ^Objects of th
34120 69 73 20 74 79 70 65 20 61 72 65 20 63 72 65 61  is type are crea
34130 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ted by [sqlite3_
34140 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  blob_open()].** 
34150 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20 62 79  and destroyed by
34160 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
34170 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  lose()]..** ^The
34180 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72   [sqlite3_blob_r
34190 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ead()] and [sqli
341a0 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29  te3_blob_write()
341b0 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ] interfaces.** 
341c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72  can be used to r
341d0 65 61 64 20 6f 72 20 77 72 69 74 65 20 73 6d 61  ead or write sma
341e0 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73 20 6f  ll subsections o
341f0 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a 20 5e  f the BLOB..** ^
34200 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  The [sqlite3_blo
34210 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72  b_bytes()] inter
34220 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
34230 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f   size of the BLO
34240 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f 0a 74  B in bytes..*/.t
34250 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
34260 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c 69 74  lite3_blob sqlit
34270 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_blob;../*.** 
34280 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 20 41  CAPI3REF: Open A
34290 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72 65 6d   BLOB For Increm
342a0 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a 2a 20  ental I/O.**.** 
342b0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
342c0 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f 42 20  s opens a [BLOB 
342d0 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c 65 5d  handle | handle]
342e0 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c 6f 63   to the BLOB loc
342f0 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77 20 69  ated.** in row i
34300 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43 6f 6c  Row, column zCol
34310 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61 62 6c  umn, table zTabl
34320 65 20 69 6e 20 64 61 74 61 62 61 73 65 20 7a 44  e in database zD
34330 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72 20 77  b;.** in other w
34340 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65 20 42  ords, the same B
34350 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64 20 62  LOB that would b
34360 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a 0a 2a  e selected by:.*
34370 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
34380 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75 6d 6e    SELECT zColumn
34390 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62 6c 65   FROM zDb.zTable
343a0 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d 20 3d   WHERE [rowid] =
343b0 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   iRow;.** </pre>
343c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  )^.**.** ^If the
343d0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
343e0 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   is non-zero, th
343f0 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20 6f  en the BLOB is o
34400 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 0a 2a  pened for read.*
34410 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63 63 65  * and write acce
34420 73 73 2e 20 5e 49 66 20 69 74 20 69 73 20 7a 65  ss. ^If it is ze
34430 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69 73 20  ro, the BLOB is 
34440 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 20  opened for read 
34450 61 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 74 20 69  access..** ^It i
34460 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
34470 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20  o open a column 
34480 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66 20  that is part of 
34490 61 6e 20 69 6e 64 65 78 20 6f 72 20 70 72 69 6d  an index or prim
344a0 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f 72 20  ary .** key for 
344b0 77 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b 66 6f  writing. ^If [fo
344c0 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
344d0 61 69 6e 74 73 5d 20 61 72 65 20 65 6e 61 62 6c  aints] are enabl
344e0 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20 6e 6f  ed, it is .** no
344f0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70  t possible to op
34500 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74  en a column that
34510 20 69 73 20 70 61 72 74 20 6f 66 20 61 20 5b 63   is part of a [c
34520 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20 77 72  hild key] for wr
34530 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  iting..**.** ^No
34540 74 65 20 74 68 61 74 20 74 68 65 20 64 61 74 61  te that the data
34550 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e 6f 74  base name is not
34560 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 74 68   the filename th
34570 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  at contains.** t
34580 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 20  he database but 
34590 72 61 74 68 65 72 20 74 68 65 20 73 79 6d 62 6f  rather the symbo
345a0 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  lic name of the 
345b0 64 61 74 61 62 61 73 65 20 74 68 61 74 0a 2a 2a  database that.**
345c0 20 61 70 70 65 61 72 73 20 61 66 74 65 72 20 74   appears after t
345d0 68 65 20 41 53 20 6b 65 79 77 6f 72 64 20 77 68  he AS keyword wh
345e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
345f0 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75 73 69  is connected usi
34600 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a 2a 20  ng [ATTACH]..** 
34610 5e 46 6f 72 20 74 68 65 20 6d 61 69 6e 20 64 61  ^For the main da
34620 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74 68 65  tabase file, the
34630 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
34640 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e 46 6f  s "main"..** ^Fo
34650 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c 20 74  r TEMP tables, t
34660 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
34670 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a 0a 2a   is "temp"..**.*
34680 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20  * ^(On success, 
34690 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
346a0 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68 65 20  eturned and the 
346b0 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  new [BLOB handle
346c0 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  ] is written.** 
346d0 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74 68 65  to *ppBlob. Othe
346e0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
346f0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
34700 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20 69 73  d and *ppBlob is
34710 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20 61 20   set.** to be a 
34720 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 29 5e 0a  null pointer.)^.
34730 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
34740 6e 20 73 65 74 73 20 74 68 65 20 5b 64 61 74 61  n sets the [data
34750 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34760 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
34770 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63 65 73  message.** acces
34780 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c 69 74  sible via [sqlit
34790 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 61 6e  e3_errcode()] an
347a0 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d [sqlite3_errms
347b0 67 28 29 5d 20 61 6e 64 20 72 65 6c 61 74 65 64  g()] and related
347c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e 20 5e  .** functions. ^
347d0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 2a 70  Note that the *p
347e0 70 42 6c 6f 62 20 76 61 72 69 61 62 6c 65 20 69  pBlob variable i
347f0 73 20 61 6c 77 61 79 73 20 69 6e 69 74 69 61 6c  s always initial
34800 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20 77 61 79  ized in a.** way
34810 20 74 68 61 74 20 6d 61 6b 65 73 20 69 74 20 73   that makes it s
34820 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73  afe to invoke [s
34830 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
34840 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f 62 0a  e()] on *ppBlob.
34850 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
34860 20 74 68 65 20 73 75 63 63 65 73 73 20 6f 72 20   the success or 
34870 66 61 69 6c 75 72 65 20 6f 66 20 74 68 69 73 20  failure of this 
34880 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e  routine..**.** ^
34890 28 49 66 20 74 68 65 20 72 6f 77 20 74 68 61 74  (If the row that
348a0 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 70   a BLOB handle p
348b0 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f 64 69  oints to is modi
348c0 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20 5b 55  fied by an.** [U
348d0 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54 45 5d  PDATE], [DELETE]
348e0 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f 4e 46  , or by [ON CONF
348f0 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66 65 63  LICT] side-effec
34900 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 42  ts.** then the B
34910 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6d 61  LOB handle is ma
34920 72 6b 65 64 20 61 73 20 22 65 78 70 69 72 65 64  rked as "expired
34930 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 74 72  "..** This is tr
34940 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75 6d 6e  ue if any column
34950 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73 20 63   of the row is c
34960 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61 20 63  hanged, even a c
34970 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72 20 74  olumn.** other t
34980 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68 65 20  han the one the 
34990 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20 6f  BLOB handle is o
349a0 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e 43 61  pen on.)^.** ^Ca
349b0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
349c0 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64  blob_read()] and
349d0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
349e0 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 61  rite()] for.** a
349f0 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20 68 61   expired BLOB ha
34a00 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68 20 61  ndle fail with a
34a10 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20 6f 66  n return code of
34a20 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
34a30 0a 2a 2a 20 5e 28 43 68 61 6e 67 65 73 20 77 72  .** ^(Changes wr
34a40 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42 4c 4f  itten into a BLO
34a50 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 42  B prior to the B
34a60 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61 72 65  LOB expiring are
34a70 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62   not.** rolled b
34a80 61 63 6b 20 62 79 20 74 68 65 20 65 78 70 69 72  ack by the expir
34a90 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42 4c 4f  ation of the BLO
34aa0 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67 65 73  B.  Such changes
34ab0 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
34ac0 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20 74 68  .** commit if th
34ad0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  e transaction co
34ae0 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
34af0 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  etion.)^.**.** ^
34b00 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  Use the [sqlite3
34b10 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
34b20 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65 74 65  nterface to dete
34b30 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65 20 6f  rmine the size o
34b40 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65 64 20  f.** the opened 
34b50 62 6c 6f 62 2e 20 20 5e 54 68 65 20 73 69 7a 65  blob.  ^The size
34b60 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79 20 6e   of a blob may n
34b70 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ot be changed by
34b80 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
34b90 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b 55 50  ce.  Use the [UP
34ba0 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d 61 6e  DATE] SQL comman
34bb0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
34bc0 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62 6c 6f  size of a.** blo
34bd0 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  b..**.** ^The [s
34be0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
34bf0 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73 71 6c  blob()] and [sql
34c00 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
34c10 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66 61 63  blob()] interfac
34c20 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20 62 75  es.** and the bu
34c30 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c 6f 62  ilt-in [zeroblob
34c40 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  ] SQL function c
34c50 61 6e 20 62 65 20 75 73 65 64 2c 20 69 66 20 64  an be used, if d
34c60 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20 63 72  esired,.** to cr
34c70 65 61 74 65 20 61 6e 20 65 6d 70 74 79 2c 20 7a  eate an empty, z
34c80 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f 62 20  ero-filled blob 
34c90 69 6e 20 77 68 69 63 68 20 74 6f 20 72 65 61 64  in which to read
34ca0 20 6f 72 20 77 72 69 74 65 20 75 73 69 6e 67 0a   or write using.
34cb0 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ** this interfac
34cc0 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76 6f 69  e..**.** To avoi
34cd0 64 20 61 20 72 65 73 6f 75 72 63 65 20 6c 65 61  d a resource lea
34ce0 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e 20 5b 42  k, every open [B
34cf0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68 6f 75  LOB handle] shou
34d00 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a  ld eventually.**
34d10 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 20   be released by 
34d20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
34d30 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
34d40 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
34d50 5f 62 6c 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71  _blob_open(.  sq
34d60 6c 69 74 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20  lite3*,.  const 
34d70 63 68 61 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e  char *zDb,.  con
34d80 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c  st char *zTable,
34d90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
34da0 43 6f 6c 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65  Column,.  sqlite
34db0 33 5f 69 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20  3_int64 iRow,.  
34dc0 69 6e 74 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c  int flags,.  sql
34dd0 69 74 65 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c  ite3_blob **ppBl
34de0 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ob.);../*.** CAP
34df0 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20 42  I3REF: Close A B
34e00 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  LOB Handle.**.**
34e10 20 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65 6e   ^Closes an open
34e20 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e 0a   [BLOB handle]..
34e30 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20 61  **.** ^Closing a
34e40 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75 73   BLOB shall caus
34e50 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 72  e the current tr
34e60 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f 6d  ansaction to com
34e70 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65 20  mit.** if there 
34e80 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c 4f  are no other BLO
34e90 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20 70  Bs, no pending p
34ea0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34eb0 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20 64  ts, and the.** d
34ec0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34ed0 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63 6f  on is in [autoco
34ee0 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20 5e  mmit mode]..** ^
34ef0 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77 65  If any writes we
34f00 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20 42  re made to the B
34f10 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74 20  LOB, they might 
34f20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68 65  be held in cache
34f30 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63 6c  .** until the cl
34f40 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 66  ose operation if
34f50 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e 0a   they will fit..
34f60 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67 20  **.** ^(Closing 
34f70 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20 66  the BLOB often f
34f80 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67 65  orces the change
34f90 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73 6b  s.** out to disk
34fa0 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20 49   and so if any I
34fb0 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72 2c  /O errors occur,
34fc0 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65 6c   they will likel
34fd0 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74 68  y occur.** at th
34fe0 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  e time when the 
34ff0 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e 20  BLOB is closed. 
35000 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61 74   Any errors that
35010 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a 2a   occur during.**
35020 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65 70   closing are rep
35030 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d 7a  orted as a non-z
35040 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ero return value
35050 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  .)^.**.** ^(The 
35060 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20 75  BLOB is closed u
35070 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e 20  nconditionally. 
35080 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72 6f   Even if this ro
35090 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a 2a  utine returns.**
350a0 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c 20   an error code, 
350b0 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69 6c  the BLOB is stil
350c0 6c 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a 2a  l closed.)^.**.*
350d0 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
350e0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 6e  routine with a n
350f0 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73 75 63  ull pointer (suc
35100 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72 65  h as would be re
35110 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61 20 66  turned.** by a f
35120 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b 73  ailed call to [s
35130 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
35140 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c 65  ()]) is a harmle
35150 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74  ss no-op..*/.int
35160 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c   sqlite3_blob_cl
35170 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ose(sqlite3_blob
35180 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   *);../*.** CAPI
35190 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65  3REF: Return The
351a0 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65 6e   Size Of An Open
351b0 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   BLOB.**.** ^Ret
351c0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69 6e  urns the size in
351d0 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42 4c   bytes of the BL
351e0 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  OB accessible vi
351f0 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65 73  a the .** succes
35200 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b 42  sfully opened [B
35210 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20 69  LOB handle] in i
35220 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  ts only argument
35230 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 72 65  .  ^The.** incre
35240 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f 20  mental blob I/O 
35250 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e 6c  routines can onl
35260 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77 72  y read or overwr
35270 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a 2a  iting existing.*
35280 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b 20  * blob content; 
35290 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61 6e  they cannot chan
352a0 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  ge the size of a
352b0 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   blob..**.** Thi
352c0 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77  s routine only w
352d0 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20  orks on a [BLOB 
352e0 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61  handle] which ha
352f0 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a  s been created.*
35300 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75 63  * by a prior suc
35310 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
35320 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
35330 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20  en()] and which 
35340 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20  has not.** been 
35350 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  closed by [sqlit
35360 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
35370 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f  .  Passing any o
35380 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a  ther pointer in.
35390 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ** to this routi
353a0 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ne results in un
353b0 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
353c0 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
353d0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69 6e   behavior..*/.in
353e0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62  t sqlite3_blob_b
353f0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c 6f  ytes(sqlite3_blo
35400 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
35410 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 74 61  I3REF: Read Data
35420 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e 63   From A BLOB Inc
35430 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a  rementally.**.**
35440 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
35450 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61 64   is used to read
35460 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f 70   data from an op
35470 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
35480 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c 65   into a.** calle
35490 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66 65  r-supplied buffe
354a0 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64 61  r. N bytes of da
354b0 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  ta are copied in
354c0 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 66  to buffer Z.** f
354d0 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f  rom the open BLO
354e0 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f  B, starting at o
354f0 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 29 5e  ffset iOffset.)^
35500 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66 73 65  .**.** ^If offse
35510 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65 73  t iOffset is les
35520 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20 66  s than N bytes f
35530 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20 74  rom the end of t
35540 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51 4c  he BLOB,.** [SQL
35550 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
35560 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
35570 74 61 20 69 73 20 72 65 61 64 2e 20 20 5e 49 66  ta is read.  ^If
35580 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69 73   N or iOffset is
35590 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a 65  .** less than ze
355a0 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ro, [SQLITE_ERRO
355b0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
355c0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65  nd no data is re
355d0 61 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 69 7a 65  ad..** ^The size
355e0 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 28 61 6e   of the blob (an
355f0 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78 69  d hence the maxi
35600 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b 69  mum value of N+i
35610 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20 62  Offset).** can b
35620 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
35630 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ng the [sqlite3_
35640 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e  blob_bytes()] in
35650 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
35660 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  An attempt to re
35670 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70 69 72  ad from an expir
35680 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  ed [BLOB handle]
35690 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a 2a   fails with an.*
356a0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66 20  * error code of 
356b0 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e 0a  [SQLITE_ABORT]..
356c0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65  **.** ^(On succe
356d0 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ss, sqlite3_blob
356e0 5f 72 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  _read() returns 
356f0 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74  SQLITE_OK..** Ot
35700 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72 72  herwise, an [err
35710 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b  or code] or an [
35720 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
35730 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
35740 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  .)^.**.** This r
35750 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b  outine only work
35760 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e  s on a [BLOB han
35770 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62  dle] which has b
35780 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62  een created.** b
35790 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73  y a prior succes
357a0 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
357b0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
357c0 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73  )] and which has
357d0 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f   not.** been clo
357e0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
357f0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20  blob_close()].  
35800 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  Passing any othe
35810 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20  r pointer in.** 
35820 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
35830 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
35840 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
35850 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  y undesirable be
35860 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65  havior..**.** Se
35870 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
35880 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e 0a  _blob_write()]..
35890 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
358a0 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65 33  lob_read(sqlite3
358b0 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a 5a  _blob *, void *Z
358c0 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f 66  , int N, int iOf
358d0 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  fset);../*.** CA
358e0 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 44 61  PI3REF: Write Da
358f0 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20 49  ta Into A BLOB I
35900 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a  ncrementally.**.
35910 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
35920 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72 69  n is used to wri
35930 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e 20  te data into an 
35940 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  open [BLOB handl
35950 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61 6c  e] from a.** cal
35960 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66  ler-supplied buf
35970 66 65 72 2e 20 5e 4e 20 62 79 74 65 73 20 6f 66  fer. ^N bytes of
35980 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65 64   data are copied
35990 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65 72   from the buffer
359a0 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 6f   Z.** into the o
359b0 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74 69  pen BLOB, starti
359c0 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f 66  ng at offset iOf
359d0 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  fset..**.** ^If 
359e0 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  the [BLOB handle
359f0 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  ] passed as the 
35a00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 77  first argument w
35a10 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66 6f  as not opened fo
35a20 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74 68  r.** writing (th
35a30 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
35a40 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  r to [sqlite3_bl
35a50 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20 7a  ob_open()] was z
35a60 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66 75  ero),.** this fu
35a70 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 5b  nction returns [
35a80 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5d  SQLITE_READONLY]
35a90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  ..**.** ^This fu
35aa0 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20  nction may only 
35ab0 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74 65  modify the conte
35ac0 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 3b  nts of the BLOB;
35ad0 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70 6f   it is.** not po
35ae0 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65 61  ssible to increa
35af0 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  se the size of a
35b00 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 69 73   BLOB using this
35b10 20 41 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66 66   API..** ^If off
35b20 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c  set iOffset is l
35b30 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73  ess than N bytes
35b40 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66   from the end of
35b50 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53   the BLOB,.** [S
35b60 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
35b70 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
35b80 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e  data is written.
35b90 20 20 5e 49 66 20 4e 20 69 73 0a 2a 2a 20 6c 65    ^If N is.** le
35ba0 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53 51  ss than zero [SQ
35bb0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
35bc0 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
35bd0 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e 0a  ata is written..
35be0 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  ** The size of t
35bf0 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 65 6e  he BLOB (and hen
35c00 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76  ce the maximum v
35c10 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65  alue of N+iOffse
35c20 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  t).** can be det
35c30 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ermined using th
35c40 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  e [sqlite3_blob_
35c50 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61  bytes()] interfa
35c60 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74  ce..**.** ^An at
35c70 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 74  tempt to write t
35c80 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c  o an expired [BL
35c90 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73  OB handle] fails
35ca0 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f   with an.** erro
35cb0 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  r code of [SQLIT
35cc0 45 5f 41 42 4f 52 54 5d 2e 20 20 5e 57 72 69 74  E_ABORT].  ^Writ
35cd0 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 74  es to the BLOB t
35ce0 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a 20  hat occurred.** 
35cf0 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f 42  before the [BLOB
35d00 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65 64   handle] expired
35d10 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64 20   are not rolled 
35d20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20 65  back by the.** e
35d30 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  xpiration of the
35d40 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68 20   handle, though 
35d50 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65 20  of course those 
35d60 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a 2a  changes might.**
35d70 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72 77   have been overw
35d80 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 73 74  ritten by the st
35d90 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78 70  atement that exp
35da0 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68 61  ired the BLOB ha
35db0 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f 74  ndle.** or by ot
35dc0 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  her independent 
35dd0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
35de0 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c 20  * ^(On success, 
35df0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69  sqlite3_blob_wri
35e00 74 65 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  te() returns SQL
35e10 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72  ITE_OK..** Other
35e20 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f 72  wise, an  [error
35e30 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65 78   code] or an [ex
35e40 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
35e50 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
35e60 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ^.**.** This rou
35e70 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20  tine only works 
35e80 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  on a [BLOB handl
35e90 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65 65  e] which has bee
35ea0 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20  n created.** by 
35eb0 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  a prior successf
35ec0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
35ed0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d  te3_blob_open()]
35ee0 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e   and which has n
35ef0 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65  ot.** been close
35f00 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c  d by [sqlite3_bl
35f10 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61  ob_close()].  Pa
35f20 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  ssing any other 
35f30 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f  pointer in.** to
35f40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
35f50 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
35f60 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
35f70 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
35f80 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  vior..**.** See 
35f90 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
35fa0 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2f 0a  lob_read()]..*/.
35fb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  int sqlite3_blob
35fc0 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f 62  _write(sqlite3_b
35fd0 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  lob *, const voi
35fe0 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  d *z, int n, int
35ff0 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a   iOffset);../*.*
36000 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
36010 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d 20  ual File System 
36020 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41 20  Objects.**.** A 
36030 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73 74  virtual filesyst
36040 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20 5b  em (VFS) is an [
36050 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
36060 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  ect.** that SQLi
36070 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65 72  te uses to inter
36080 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  act.** with the 
36090 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
360a0 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d 6f  ting system.  Mo
360b0 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64 73  st SQLite builds
360c0 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a 20   come with a.** 
360d0 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20 56  single default V
360e0 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72 6f  FS that is appro
360f0 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20 68  priate for the h
36100 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a 2a  ost computer..**
36110 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20 62   New VFSes can b
36120 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64  e registered and
36130 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73 20   existing VFSes 
36140 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74 65  can be unregiste
36150 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c  red..** The foll
36160 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  owing interfaces
36170 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a 2a   are provided..*
36180 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36190 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e 74  3_vfs_find() int
361a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
361b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56 46   pointer to a VF
361c0 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  S given its name
361d0 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20  ..** ^Names are 
361e0 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e 0a  case sensitive..
361f0 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20 7a 65  ** ^Names are ze
36200 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
36210 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
36220 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
36230 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70 6f  match, a NULL po
36240 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
36250 64 2e 0a 2a 2a 20 5e 49 66 20 7a 56 66 73 4e 61  d..** ^If zVfsNa
36260 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  me is NULL then 
36270 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
36280 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
36290 2a 2a 20 5e 4e 65 77 20 56 46 53 65 73 20 61 72  ** ^New VFSes ar
362a0 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  e registered wit
362b0 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65  h sqlite3_vfs_re
362c0 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 5e 45 61  gister()..** ^Ea
362d0 63 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f 6d  ch new VFS becom
362e0 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  es the default V
362f0 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44 66  FS if the makeDf
36300 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e 0a  lt flag is set..
36310 2a 2a 20 5e 54 68 65 20 73 61 6d 65 20 56 46 53  ** ^The same VFS
36320 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
36330 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ed multiple time
36340 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72 79  s without injury
36350 2e 0a 2a 2a 20 5e 54 6f 20 6d 61 6b 65 20 61 6e  ..** ^To make an
36360 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69 6e   existing VFS in
36370 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  to the default V
36380 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74 20  FS, register it 
36390 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74 68  again.** with th
363a0 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20  e makeDflt flag 
363b0 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69 66  set.  If two dif
363c0 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 69 74  ferent VFSes wit
363d0 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e 61  h the.** same na
363e0 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 72 65  me are registere
363f0 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  d, the behavior 
36400 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 49  is undefined.  I
36410 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72 65  f a.** VFS is re
36420 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61 20  gistered with a 
36430 6e 61 6d 65 20 74 68 61 74 20 69 73 20 4e 55 4c  name that is NUL
36440 4c 20 6f 72 20 61 6e 20 65 6d 70 74 79 20 73 74  L or an empty st
36450 72 69 6e 67 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ring,.** then th
36460 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
36470 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
36480 55 6e 72 65 67 69 73 74 65 72 20 61 20 56 46 53  Unregister a VFS
36490 20 77 69 74 68 20 74 68 65 20 73 71 6c 69 74 65   with the sqlite
364a0 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
364b0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  () interface..**
364c0 20 5e 28 49 66 20 74 68 65 20 64 65 66 61 75 6c   ^(If the defaul
364d0 74 20 56 46 53 20 69 73 20 75 6e 72 65 67 69 73  t VFS is unregis
364e0 74 65 72 65 64 2c 20 61 6e 6f 74 68 65 72 20 56  tered, another V
364f0 46 53 20 69 73 20 63 68 6f 73 65 6e 20 61 73 0a  FS is chosen as.
36500 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 20  ** the default. 
36510 20 54 68 65 20 63 68 6f 69 63 65 20 66 6f 72 20   The choice for 
36520 74 68 65 20 6e 65 77 20 56 46 53 20 69 73 20 61  the new VFS is a
36530 72 62 69 74 72 61 72 79 2e 29 5e 0a 2a 2f 0a 73  rbitrary.)^.*/.s
36540 71 6c 69 74 65 33 5f 76 66 73 20 2a 73 71 6c 69  qlite3_vfs *sqli
36550 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 63 6f 6e  te3_vfs_find(con
36560 73 74 20 63 68 61 72 20 2a 7a 56 66 73 4e 61 6d  st char *zVfsNam
36570 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
36580 76 66 73 5f 72 65 67 69 73 74 65 72 28 73 71 6c  vfs_register(sql
36590 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d  ite3_vfs*, int m
365a0 61 6b 65 44 66 6c 74 29 3b 0a 69 6e 74 20 73 71  akeDflt);.int sq
365b0 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
365c0 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
365d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
365e0 52 45 46 3a 20 4d 75 74 65 78 65 73 0a 2a 2a 0a  REF: Mutexes.**.
365f0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
36600 72 65 20 75 73 65 73 20 74 68 65 73 65 20 72 6f  re uses these ro
36610 75 74 69 6e 65 73 20 66 6f 72 20 74 68 72 65 61  utines for threa
36620 64 0a 2a 2a 20 73 79 6e 63 68 72 6f 6e 69 7a 61  d.** synchroniza
36630 74 69 6f 6e 2e 20 54 68 6f 75 67 68 20 74 68 65  tion. Though the
36640 79 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  y are intended f
36650 6f 72 20 69 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75  or internal.** u
36660 73 65 20 62 79 20 53 51 4c 69 74 65 2c 20 63 6f  se by SQLite, co
36670 64 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  de that links ag
36680 61 69 6e 73 74 20 53 51 4c 69 74 65 20 69 73 0a  ainst SQLite is.
36690 2a 2a 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  ** permitted to 
366a0 75 73 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  use any of these
366b0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
366c0 20 54 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72   The SQLite sour
366d0 63 65 20 63 6f 64 65 20 63 6f 6e 74 61 69 6e 73  ce code contains
366e0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
366f0 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 6f 66 20  entations.** of 
36700 74 68 65 73 65 20 6d 75 74 65 78 20 72 6f 75 74  these mutex rout
36710 69 6e 65 73 2e 20 20 41 6e 20 61 70 70 72 6f 70  ines.  An approp
36720 72 69 61 74 65 20 69 6d 70 6c 65 6d 65 6e 74 61  riate implementa
36730 74 69 6f 6e 0a 2a 2a 20 69 73 20 73 65 6c 65 63  tion.** is selec
36740 74 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ted automaticall
36750 79 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  y at compile-tim
36760 65 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  e.  ^(The follow
36770 69 6e 67 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ing.** implement
36780 61 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69 6c  ations are avail
36790 61 62 6c 65 20 69 6e 20 74 68 65 20 53 51 4c 69  able in the SQLi
367a0 74 65 20 63 6f 72 65 3a 0a 2a 2a 0a 2a 2a 20 3c  te core:.**.** <
367b0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51  ul>.** <li>   SQ
367c0 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 0a 2a  LITE_MUTEX_OS2.*
367d0 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f  * <li>   SQLITE_
367e0 4d 55 54 45 58 5f 50 54 48 52 45 41 44 0a 2a 2a  MUTEX_PTHREAD.**
367f0 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d   <li>   SQLITE_M
36800 55 54 45 58 5f 57 33 32 0a 2a 2a 20 3c 6c 69 3e  UTEX_W32.** <li>
36810 20 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f     SQLITE_MUTEX_
36820 4e 4f 4f 50 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NOOP.** </ul>)^.
36830 2a 2a 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54  **.** ^The SQLIT
36840 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 20 69 6d 70  E_MUTEX_NOOP imp
36850 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61  lementation is a
36860 20 73 65 74 20 6f 66 20 72 6f 75 74 69 6e 65 73   set of routines
36870 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
36880 20 72 65 61 6c 20 6c 6f 63 6b 69 6e 67 20 61 6e   real locking an
36890 64 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65  d is appropriate
368a0 20 66 6f 72 20 75 73 65 20 69 6e 0a 2a 2a 20 61   for use in.** a
368b0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
368c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 5e   application.  ^
368d0 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  The SQLITE_MUTEX
368e0 5f 4f 53 32 2c 0a 2a 2a 20 53 51 4c 49 54 45 5f  _OS2,.** SQLITE_
368f0 4d 55 54 45 58 5f 50 54 48 52 45 41 44 2c 20 61  MUTEX_PTHREAD, a
36900 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
36910 57 33 32 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  W32 implementati
36920 6f 6e 73 0a 2a 2a 20 61 72 65 20 61 70 70 72 6f  ons.** are appro
36930 70 72 69 61 74 65 20 66 6f 72 20 75 73 65 20 6f  priate for use o
36940 6e 20 4f 53 2f 32 2c 20 55 6e 69 78 2c 20 61 6e  n OS/2, Unix, an
36950 64 20 57 69 6e 64 6f 77 73 2e 0a 2a 2a 0a 2a 2a  d Windows..**.**
36960 20 5e 28 49 66 20 53 51 4c 69 74 65 20 69 73 20   ^(If SQLite is 
36970 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
36980 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 41  e SQLITE_MUTEX_A
36990 50 50 44 45 46 20 70 72 65 70 72 6f 63 65 73 73  PPDEF preprocess
369a0 6f 72 0a 2a 2a 20 6d 61 63 72 6f 20 64 65 66 69  or.** macro defi
369b0 6e 65 64 20 28 77 69 74 68 20 22 2d 44 53 51 4c  ned (with "-DSQL
369c0 49 54 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46  ITE_MUTEX_APPDEF
369d0 3d 31 22 29 2c 20 74 68 65 6e 20 6e 6f 20 6d 75  =1"), then no mu
369e0 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
369f0 61 74 69 6f 6e 20 69 73 20 69 6e 63 6c 75 64 65  ation is include
36a00 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
36a10 72 79 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65  ry. In this case
36a20 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
36a30 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
36a40 61 20 63 75 73 74 6f 6d 20 6d 75 74 65 78 20 69  a custom mutex i
36a50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73  mplementation us
36a60 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
36a70 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
36a80 20 6f 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 73   option of the s
36a90 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
36aa0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 66 6f  function.** befo
36ab0 72 65 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  re calling sqlit
36ac0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
36ad0 6f 72 20 61 6e 79 20 6f 74 68 65 72 20 70 75 62  or any other pub
36ae0 6c 69 63 20 73 71 6c 69 74 65 33 5f 0a 2a 2a 20  lic sqlite3_.** 
36af0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 63 61  function that ca
36b00 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
36b10 69 61 6c 69 7a 65 28 29 2e 29 5e 0a 2a 2a 0a 2a  ialize().)^.**.*
36b20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
36b30 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 72 6f 75  utex_alloc() rou
36b40 74 69 6e 65 20 61 6c 6c 6f 63 61 74 65 73 20 61  tine allocates a
36b50 20 6e 65 77 0a 2a 2a 20 6d 75 74 65 78 20 61 6e   new.** mutex an
36b60 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
36b70 74 65 72 20 74 6f 20 69 74 2e 20 5e 49 66 20 69  ter to it. ^If i
36b80 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 0a 2a  t returns NULL.*
36b90 2a 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 61  * that means tha
36ba0 74 20 61 20 6d 75 74 65 78 20 63 6f 75 6c 64 20  t a mutex could 
36bb0 6e 6f 74 20 62 65 20 61 6c 6c 6f 63 61 74 65 64  not be allocated
36bc0 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 77 69  .  ^SQLite.** wi
36bd0 6c 6c 20 75 6e 77 69 6e 64 20 69 74 73 20 73 74  ll unwind its st
36be0 61 63 6b 20 61 6e 64 20 72 65 74 75 72 6e 20 61  ack and return a
36bf0 6e 20 65 72 72 6f 72 2e 20 20 5e 28 54 68 65 20  n error.  ^(The 
36c00 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73  argument.** to s
36c10 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
36c20 6f 63 28 29 20 69 73 20 6f 6e 65 20 6f 66 20 74  oc() is one of t
36c30 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
36c40 73 74 61 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  stants:.**.** <u
36c50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
36c60 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a  TE_MUTEX_FAST.**
36c70 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
36c80 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a  TEX_RECURSIVE.**
36c90 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
36ca0 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
36cb0 52 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  R.** <li>  SQLIT
36cc0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
36cd0 45 4d 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  EM.** <li>  SQLI
36ce0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
36cf0 4d 45 4d 32 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  MEM2.** <li>  SQ
36d00 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
36d10 43 5f 50 52 4e 47 0a 2a 2a 20 3c 6c 69 3e 20 20  C_PRNG.** <li>  
36d20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
36d30 54 49 43 5f 4c 52 55 0a 2a 2a 20 3c 6c 69 3e 20  TIC_LRU.** <li> 
36d40 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
36d50 41 54 49 43 5f 4c 52 55 32 0a 2a 2a 20 3c 2f 75  ATIC_LRU2.** </u
36d60 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  l>)^.**.** ^The 
36d70 66 69 72 73 74 20 74 77 6f 20 63 6f 6e 73 74 61  first two consta
36d80 6e 74 73 20 28 53 51 4c 49 54 45 5f 4d 55 54 45  nts (SQLITE_MUTE
36d90 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c 49 54  X_FAST and SQLIT
36da0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
36db0 45 29 0a 2a 2a 20 63 61 75 73 65 20 73 71 6c 69  E).** cause sqli
36dc0 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
36dd0 29 20 74 6f 20 63 72 65 61 74 65 0a 2a 2a 20 61  ) to create.** a
36de0 20 6e 65 77 20 6d 75 74 65 78 2e 20 20 5e 54 68   new mutex.  ^Th
36df0 65 20 6e 65 77 20 6d 75 74 65 78 20 69 73 20 72  e new mutex is r
36e00 65 63 75 72 73 69 76 65 20 77 68 65 6e 20 53 51  ecursive when SQ
36e10 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
36e20 53 49 56 45 0a 2a 2a 20 69 73 20 75 73 65 64 20  SIVE.** is used 
36e30 62 75 74 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  but not necessar
36e40 69 6c 79 20 73 6f 20 77 68 65 6e 20 53 51 4c 49  ily so when SQLI
36e50 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69 73  TE_MUTEX_FAST is
36e60 20 75 73 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 75   used..** The mu
36e70 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  tex implementati
36e80 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
36e90 20 74 6f 20 6d 61 6b 65 20 61 20 64 69 73 74 69   to make a disti
36ea0 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
36eb0 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  n SQLITE_MUTEX_R
36ec0 45 43 55 52 53 49 56 45 20 61 6e 64 20 53 51 4c  ECURSIVE and SQL
36ed0 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 69  ITE_MUTEX_FAST i
36ee0 66 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  f it does.** not
36ef0 20 77 61 6e 74 20 74 6f 2e 20 20 5e 53 51 4c 69   want to.  ^SQLi
36f00 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 72 65 71  te will only req
36f10 75 65 73 74 20 61 20 72 65 63 75 72 73 69 76 65  uest a recursive
36f20 20 6d 75 74 65 78 20 69 6e 0a 2a 2a 20 63 61 73   mutex in.** cas
36f30 65 73 20 77 68 65 72 65 20 69 74 20 72 65 61 6c  es where it real
36f40 6c 79 20 6e 65 65 64 73 20 6f 6e 65 2e 20 20 5e  ly needs one.  ^
36f50 49 66 20 61 20 66 61 73 74 65 72 20 6e 6f 6e 2d  If a faster non-
36f60 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 0a  recursive mutex.
36f70 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
36f80 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 6f  n is available o
36f90 6e 20 74 68 65 20 68 6f 73 74 20 70 6c 61 74 66  n the host platf
36fa0 6f 72 6d 2c 20 74 68 65 20 6d 75 74 65 78 20 73  orm, the mutex s
36fb0 75 62 73 79 73 74 65 6d 0a 2a 2a 20 6d 69 67 68  ubsystem.** migh
36fc0 74 20 72 65 74 75 72 6e 20 73 75 63 68 20 61 20  t return such a 
36fd0 6d 75 74 65 78 20 69 6e 20 72 65 73 70 6f 6e 73  mutex in respons
36fe0 65 20 74 6f 20 53 51 4c 49 54 45 5f 4d 55 54 45  e to SQLITE_MUTE
36ff0 58 5f 46 41 53 54 2e 0a 2a 2a 0a 2a 2a 20 5e 54  X_FAST..**.** ^T
37000 68 65 20 6f 74 68 65 72 20 61 6c 6c 6f 77 65 64  he other allowed
37010 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 73   parameters to s
37020 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
37030 6f 63 28 29 20 28 61 6e 79 74 68 69 6e 67 20 6f  oc() (anything o
37040 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 53 51 4c  ther.** than SQL
37050 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 61  ITE_MUTEX_FAST a
37060 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
37070 52 45 43 55 52 53 49 56 45 29 20 65 61 63 68 20  RECURSIVE) each 
37080 72 65 74 75 72 6e 0a 2a 2a 20 61 20 70 6f 69 6e  return.** a poin
37090 74 65 72 20 74 6f 20 61 20 73 74 61 74 69 63 20  ter to a static 
370a0 70 72 65 65 78 69 73 74 69 6e 67 20 6d 75 74 65  preexisting mute
370b0 78 2e 20 20 5e 53 69 78 20 73 74 61 74 69 63 20  x.  ^Six static 
370c0 6d 75 74 65 78 65 73 20 61 72 65 0a 2a 2a 20 75  mutexes are.** u
370d0 73 65 64 20 62 79 20 74 68 65 20 63 75 72 72 65  sed by the curre
370e0 6e 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  nt version of SQ
370f0 4c 69 74 65 2e 20 20 46 75 74 75 72 65 20 76 65  Lite.  Future ve
37100 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
37110 0a 2a 2a 20 6d 61 79 20 61 64 64 20 61 64 64 69  .** may add addi
37120 74 69 6f 6e 61 6c 20 73 74 61 74 69 63 20 6d 75  tional static mu
37130 74 65 78 65 73 2e 20 20 53 74 61 74 69 63 20 6d  texes.  Static m
37140 75 74 65 78 65 73 20 61 72 65 20 66 6f 72 20 69  utexes are for i
37150 6e 74 65 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62  nternal.** use b
37160 79 20 53 51 4c 69 74 65 20 6f 6e 6c 79 2e 20 20  y SQLite only.  
37170 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
37180 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 75 74  t use SQLite mut
37190 65 78 65 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 75  exes should.** u
371a0 73 65 20 6f 6e 6c 79 20 74 68 65 20 64 79 6e 61  se only the dyna
371b0 6d 69 63 20 6d 75 74 65 78 65 73 20 72 65 74 75  mic mutexes retu
371c0 72 6e 65 64 20 62 79 20 53 51 4c 49 54 45 5f 4d  rned by SQLITE_M
371d0 55 54 45 58 5f 46 41 53 54 20 6f 72 0a 2a 2a 20  UTEX_FAST or.** 
371e0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
371f0 55 52 53 49 56 45 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  URSIVE..**.** ^N
37200 6f 74 65 20 74 68 61 74 20 69 66 20 6f 6e 65 20  ote that if one 
37210 6f 66 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d  of the dynamic m
37220 75 74 65 78 20 70 61 72 61 6d 65 74 65 72 73 20  utex parameters 
37230 28 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41  (SQLITE_MUTEX_FA
37240 53 54 0a 2a 2a 20 6f 72 20 53 51 4c 49 54 45 5f  ST.** or SQLITE_
37250 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 29  MUTEX_RECURSIVE)
37260 20 69 73 20 75 73 65 64 20 74 68 65 6e 20 73 71   is used then sq
37270 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
37280 63 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  c().** returns a
37290 20 64 69 66 66 65 72 65 6e 74 20 6d 75 74 65 78   different mutex
372a0 20 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 2e 20   on every call. 
372b0 20 5e 42 75 74 20 66 6f 72 20 74 68 65 20 73 74   ^But for the st
372c0 61 74 69 63 0a 2a 2a 20 6d 75 74 65 78 20 74 79  atic.** mutex ty
372d0 70 65 73 2c 20 74 68 65 20 73 61 6d 65 20 6d 75  pes, the same mu
372e0 74 65 78 20 69 73 20 72 65 74 75 72 6e 65 64 20  tex is returned 
372f0 6f 6e 20 65 76 65 72 79 20 63 61 6c 6c 20 74 68  on every call th
37300 61 74 20 68 61 73 0a 2a 2a 20 74 68 65 20 73 61  at has.** the sa
37310 6d 65 20 74 79 70 65 20 6e 75 6d 62 65 72 2e 0a  me type number..
37320 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37330 65 33 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 20  e3_mutex_free() 
37340 72 6f 75 74 69 6e 65 20 64 65 61 6c 6c 6f 63 61  routine dealloca
37350 74 65 73 20 61 20 70 72 65 76 69 6f 75 73 6c 79  tes a previously
37360 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64 20 64 79  .** allocated dy
37370 6e 61 6d 69 63 20 6d 75 74 65 78 2e 20 20 5e 53  namic mutex.  ^S
37380 51 4c 69 74 65 20 69 73 20 63 61 72 65 66 75 6c  QLite is careful
37390 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65 20 65   to deallocate e
373a0 76 65 72 79 0a 2a 2a 20 64 79 6e 61 6d 69 63 20  very.** dynamic 
373b0 6d 75 74 65 78 20 74 68 61 74 20 69 74 20 61 6c  mutex that it al
373c0 6c 6f 63 61 74 65 73 2e 20 20 54 68 65 20 64 79  locates.  The dy
373d0 6e 61 6d 69 63 20 6d 75 74 65 78 65 73 20 6d 75  namic mutexes mu
373e0 73 74 20 6e 6f 74 20 62 65 20 69 6e 0a 2a 2a 20  st not be in.** 
373f0 75 73 65 20 77 68 65 6e 20 74 68 65 79 20 61 72  use when they ar
37400 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 20 20  e deallocated.  
37410 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 65  Attempting to de
37420 61 6c 6c 6f 63 61 74 65 20 61 20 73 74 61 74 69  allocate a stati
37430 63 0a 2a 2a 20 6d 75 74 65 78 20 72 65 73 75 6c  c.** mutex resul
37440 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
37450 62 65 68 61 76 69 6f 72 2e 20 20 5e 53 51 4c 69  behavior.  ^SQLi
37460 74 65 20 6e 65 76 65 72 20 64 65 61 6c 6c 6f 63  te never dealloc
37470 61 74 65 73 0a 2a 2a 20 61 20 73 74 61 74 69 63  ates.** a static
37480 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e 54   mutex..**.** ^T
37490 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
374a0 5f 65 6e 74 65 72 28 29 20 61 6e 64 20 73 71 6c  _enter() and sql
374b0 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28 29  ite3_mutex_try()
374c0 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
374d0 74 0a 2a 2a 20 74 6f 20 65 6e 74 65 72 20 61 20  t.** to enter a 
374e0 6d 75 74 65 78 2e 20 20 5e 49 66 20 61 6e 6f 74  mutex.  ^If anot
374f0 68 65 72 20 74 68 72 65 61 64 20 69 73 20 61 6c  her thread is al
37500 72 65 61 64 79 20 77 69 74 68 69 6e 20 74 68 65  ready within the
37510 20 6d 75 74 65 78 2c 0a 2a 2a 20 73 71 6c 69 74   mutex,.** sqlit
37520 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
37530 20 77 69 6c 6c 20 62 6c 6f 63 6b 20 61 6e 64 20   will block and 
37540 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
37550 79 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  y() will return.
37560 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20  ** SQLITE_BUSY. 
37570 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75   ^The sqlite3_mu
37580 74 65 78 5f 74 72 79 28 29 20 69 6e 74 65 72 66  tex_try() interf
37590 61 63 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ace returns [SQL
375a0 49 54 45 5f 4f 4b 5d 0a 2a 2a 20 75 70 6f 6e 20  ITE_OK].** upon 
375b0 73 75 63 63 65 73 73 66 75 6c 20 65 6e 74 72 79  successful entry
375c0 2e 20 20 5e 28 4d 75 74 65 78 65 73 20 63 72 65  .  ^(Mutexes cre
375d0 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ated using.** SQ
375e0 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52  LITE_MUTEX_RECUR
375f0 53 49 56 45 20 63 61 6e 20 62 65 20 65 6e 74 65  SIVE can be ente
37600 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
37610 65 73 20 62 79 20 74 68 65 20 73 61 6d 65 20 74  es by the same t
37620 68 72 65 61 64 2e 0a 2a 2a 20 49 6e 20 73 75 63  hread..** In suc
37630 68 20 63 61 73 65 73 20 74 68 65 2c 0a 2a 2a 20  h cases the,.** 
37640 6d 75 74 65 78 20 6d 75 73 74 20 62 65 20 65 78  mutex must be ex
37650 69 74 65 64 20 61 6e 20 65 71 75 61 6c 20 6e 75  ited an equal nu
37660 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 62 65  mber of times be
37670 66 6f 72 65 20 61 6e 6f 74 68 65 72 20 74 68 72  fore another thr
37680 65 61 64 0a 2a 2a 20 63 61 6e 20 65 6e 74 65 72  ead.** can enter
37690 2e 29 5e 20 20 5e 28 49 66 20 74 68 65 20 73 61  .)^  ^(If the sa
376a0 6d 65 20 74 68 72 65 61 64 20 74 72 69 65 73 20  me thread tries 
376b0 74 6f 20 65 6e 74 65 72 20 61 6e 79 20 6f 74 68  to enter any oth
376c0 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 6d 75  er.** kind of mu
376d0 74 65 78 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  tex more than on
376e0 63 65 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ce, the behavior
376f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
37700 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
37710 76 65 72 20 65 78 68 69 62 69 74 0a 2a 2a 20 73  ver exhibit.** s
37720 75 63 68 20 62 65 68 61 76 69 6f 72 20 69 6e 20  uch behavior in 
37730 69 74 73 20 6f 77 6e 20 75 73 65 20 6f 66 20 6d  its own use of m
37740 75 74 65 78 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  utexes.)^.**.** 
37750 5e 28 53 6f 6d 65 20 73 79 73 74 65 6d 73 20 28  ^(Some systems (
37760 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 57 69 6e  for example, Win
37770 64 6f 77 73 20 39 35 29 20 64 6f 20 6e 6f 74 20  dows 95) do not 
37780 73 75 70 70 6f 72 74 20 74 68 65 20 6f 70 65 72  support the oper
37790 61 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ation.** impleme
377a0 6e 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  nted by sqlite3_
377b0 6d 75 74 65 78 5f 74 72 79 28 29 2e 20 20 4f 6e  mutex_try().  On
377c0 20 74 68 6f 73 65 20 73 79 73 74 65 6d 73 2c 20   those systems, 
377d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
377e0 79 28 29 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61  y().** will alwa
377f0 79 73 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ys return SQLITE
37800 5f 42 55 53 59 2e 20 20 54 68 65 20 53 51 4c 69  _BUSY.  The SQLi
37810 74 65 20 63 6f 72 65 20 6f 6e 6c 79 20 65 76 65  te core only eve
37820 72 20 75 73 65 73 0a 2a 2a 20 73 71 6c 69 74 65  r uses.** sqlite
37830 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 61 73  3_mutex_try() as
37840 20 61 6e 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e   an optimization
37850 20 73 6f 20 74 68 69 73 20 69 73 20 61 63 63 65   so this is acce
37860 70 74 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  ptable behavior.
37870 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
37880 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
37890 65 28 29 20 72 6f 75 74 69 6e 65 20 65 78 69 74  e() routine exit
378a0 73 20 61 20 6d 75 74 65 78 20 74 68 61 74 20 77  s a mutex that w
378b0 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
378c0 20 65 6e 74 65 72 65 64 20 62 79 20 74 68 65 20   entered by the 
378d0 73 61 6d 65 20 74 68 72 65 61 64 2e 20 20 20 5e  same thread.   ^
378e0 28 54 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a  (The behavior.**
378f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 69 66   is undefined if
37900 20 74 68 65 20 6d 75 74 65 78 20 69 73 20 6e 6f   the mutex is no
37910 74 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  t currently ente
37920 72 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  red by the.** ca
37930 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 6f 72 20  lling thread or 
37940 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
37950 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 53 51 4c   allocated.  SQL
37960 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 6e 65 76 65  ite will.** neve
37970 72 20 64 6f 20 65 69 74 68 65 72 2e 29 5e 0a 2a  r do either.)^.*
37980 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72 67  *.** ^If the arg
37990 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
379a0 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 2c 20  _mutex_enter(), 
379b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
379c0 79 28 29 2c 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  y(), or.** sqlit
379d0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29  e3_mutex_leave()
379e0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
379f0 65 72 2c 20 74 68 65 6e 20 61 6c 6c 20 74 68 72  er, then all thr
37a00 65 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 62  ee routines.** b
37a10 65 68 61 76 65 20 61 73 20 6e 6f 2d 6f 70 73 2e  ehave as no-ops.
37a20 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
37a30 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
37a40 68 65 6c 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  held()] and [sql
37a50 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
37a60 6c 64 28 29 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  ld()]..*/.sqlite
37a70 33 5f 6d 75 74 65 78 20 2a 73 71 6c 69 74 65 33  3_mutex *sqlite3
37a80 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 69 6e 74  _mutex_alloc(int
37a90 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37aa0 6d 75 74 65 78 5f 66 72 65 65 28 73 71 6c 69 74  mutex_free(sqlit
37ab0 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69 64  e3_mutex*);.void
37ac0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
37ad0 6e 74 65 72 28 73 71 6c 69 74 65 33 5f 6d 75 74  nter(sqlite3_mut
37ae0 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ex*);.int sqlite
37af0 33 5f 6d 75 74 65 78 5f 74 72 79 28 73 71 6c 69  3_mutex_try(sqli
37b00 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 76 6f 69  te3_mutex*);.voi
37b10 64 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  d sqlite3_mutex_
37b20 6c 65 61 76 65 28 73 71 6c 69 74 65 33 5f 6d 75  leave(sqlite3_mu
37b30 74 65 78 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tex*);../*.** CA
37b40 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 4d 65  PI3REF: Mutex Me
37b50 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
37b60 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
37b70 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
37b80 20 64 65 66 69 6e 65 73 20 74 68 65 20 6c 6f 77   defines the low
37b90 2d 6c 65 76 65 6c 20 72 6f 75 74 69 6e 65 73 0a  -level routines.
37ba0 2a 2a 20 75 73 65 64 20 74 6f 20 61 6c 6c 6f 63  ** used to alloc
37bb0 61 74 65 20 61 6e 64 20 75 73 65 20 6d 75 74 65  ate and use mute
37bc0 78 65 73 2e 0a 2a 2a 0a 2a 2a 20 55 73 75 61 6c  xes..**.** Usual
37bd0 6c 79 2c 20 74 68 65 20 64 65 66 61 75 6c 74 20  ly, the default 
37be0 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74 61  mutex implementa
37bf0 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 64 20 62  tions provided b
37c00 79 20 53 51 4c 69 74 65 20 61 72 65 0a 2a 2a 20  y SQLite are.** 
37c10 73 75 66 66 69 63 69 65 6e 74 2c 20 68 6f 77 65  sufficient, howe
37c20 76 65 72 20 74 68 65 20 75 73 65 72 20 68 61 73  ver the user has
37c30 20 74 68 65 20 6f 70 74 69 6f 6e 20 6f 66 20 73   the option of s
37c40 75 62 73 74 69 74 75 74 69 6e 67 20 61 20 63 75  ubstituting a cu
37c50 73 74 6f 6d 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  stom.** implemen
37c60 74 61 74 69 6f 6e 20 66 6f 72 20 73 70 65 63 69  tation for speci
37c70 61 6c 69 7a 65 64 20 64 65 70 6c 6f 79 6d 65 6e  alized deploymen
37c80 74 73 20 6f 72 20 73 79 73 74 65 6d 73 20 66 6f  ts or systems fo
37c90 72 20 77 68 69 63 68 20 53 51 4c 69 74 65 0a 2a  r which SQLite.*
37ca0 2a 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69  * does not provi
37cb0 64 65 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  de a suitable im
37cc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 49 6e  plementation. In
37cd0 20 74 68 69 73 20 63 61 73 65 2c 20 74 68 65 20   this case, the 
37ce0 75 73 65 72 0a 2a 2a 20 63 72 65 61 74 65 73 20  user.** creates 
37cf0 61 6e 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  and populates an
37d00 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
37d10 73 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 70  s structure to p
37d20 61 73 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ass.** to sqlite
37d30 33 5f 63 6f 6e 66 69 67 28 29 20 61 6c 6f 6e 67  3_config() along
37d40 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
37d50 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 20  E_CONFIG_MUTEX] 
37d60 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 64 64 69 74  option..** Addit
37d70 69 6f 6e 61 6c 6c 79 2c 20 61 6e 20 69 6e 73 74  ionally, an inst
37d80 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
37d90 75 63 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  ucture can be us
37da0 65 64 20 61 73 20 61 6e 0a 2a 2a 20 6f 75 74 70  ed as an.** outp
37db0 75 74 20 76 61 72 69 61 62 6c 65 20 77 68 65 6e  ut variable when
37dc0 20 71 75 65 72 79 69 6e 67 20 74 68 65 20 73 79   querying the sy
37dd0 73 74 65 6d 20 66 6f 72 20 74 68 65 20 63 75 72  stem for the cur
37de0 72 65 6e 74 20 6d 75 74 65 78 0a 2a 2a 20 69 6d  rent mutex.** im
37df0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 75 73  plementation, us
37e00 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
37e10 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
37e20 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   option..**.** ^
37e30 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d  The xMutexInit m
37e40 65 74 68 6f 64 20 64 65 66 69 6e 65 64 20 62 79  ethod defined by
37e50 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
37e60 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a  is invoked as.**
37e70 20 70 61 72 74 20 6f 66 20 73 79 73 74 65 6d 20   part of system 
37e80 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 62  initialization b
37e90 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
37ea0 69 74 69 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  itialize() funct
37eb0 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 20 78 4d 75  ion..** ^The xMu
37ec0 74 65 78 49 6e 69 74 20 72 6f 75 74 69 6e 65 20  texInit routine 
37ed0 69 73 20 63 61 6c 6c 65 20 62 79 20 53 51 4c 69  is calle by SQLi
37ee0 74 65 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20  te exactly once 
37ef0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 65 66 66 65  for each.** effe
37f00 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 5b 73  ctive call to [s
37f10 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
37f20 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  e()]..**.** ^The
37f30 20 78 4d 75 74 65 78 45 6e 64 20 6d 65 74 68 6f   xMutexEnd metho
37f40 64 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69  d defined by thi
37f50 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 69  s structure is i
37f60 6e 76 6f 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72  nvoked as.** par
37f70 74 20 6f 66 20 73 79 73 74 65 6d 20 73 68 75 74  t of system shut
37f80 64 6f 77 6e 20 62 79 20 74 68 65 20 73 71 6c 69  down by the sqli
37f90 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 66  te3_shutdown() f
37fa0 75 6e 63 74 69 6f 6e 2e 20 54 68 65 0a 2a 2a 20  unction. The.** 
37fb0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
37fc0 66 20 74 68 69 73 20 6d 65 74 68 6f 64 20 69 73  f this method is
37fd0 20 65 78 70 65 63 74 65 64 20 74 6f 20 72 65 6c   expected to rel
37fe0 65 61 73 65 20 61 6c 6c 20 6f 75 74 73 74 61 6e  ease all outstan
37ff0 64 69 6e 67 0a 2a 2a 20 72 65 73 6f 75 72 63 65  ding.** resource
38000 73 20 6f 62 74 61 69 6e 65 64 20 62 79 20 74 68  s obtained by th
38010 65 20 6d 75 74 65 78 20 6d 65 74 68 6f 64 73 20  e mutex methods 
38020 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
38030 65 73 70 65 63 69 61 6c 6c 79 0a 2a 2a 20 74 68  especially.** th
38040 6f 73 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20  ose obtained by 
38050 74 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20 6d  the xMutexInit m
38060 65 74 68 6f 64 2e 20 20 5e 54 68 65 20 78 4d 75  ethod.  ^The xMu
38070 74 65 78 45 6e 64 28 29 0a 2a 2a 20 69 6e 74 65  texEnd().** inte
38080 72 66 61 63 65 20 69 73 20 69 6e 76 6f 6b 65 64  rface is invoked
38090 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 20 66 6f   exactly once fo
380a0 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 5b  r each call to [
380b0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
380c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ()]..**.** ^(The
380d0 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 76 65 6e   remaining seven
380e0 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e 65 64   methods defined
380f0 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74 75   by this structu
38100 72 65 20 28 78 4d 75 74 65 78 41 6c 6c 6f 63 2c  re (xMutexAlloc,
38110 0a 2a 2a 20 78 4d 75 74 65 78 46 72 65 65 2c 20  .** xMutexFree, 
38120 78 4d 75 74 65 78 45 6e 74 65 72 2c 20 78 4d 75  xMutexEnter, xMu
38130 74 65 78 54 72 79 2c 20 78 4d 75 74 65 78 4c 65  texTry, xMutexLe
38140 61 76 65 2c 20 78 4d 75 74 65 78 48 65 6c 64 20  ave, xMutexHeld 
38150 61 6e 64 0a 2a 2a 20 78 4d 75 74 65 78 4e 6f 74  and.** xMutexNot
38160 68 65 6c 64 29 20 69 6d 70 6c 65 6d 65 6e 74 20  held) implement 
38170 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  the following in
38180 74 65 72 66 61 63 65 73 20 28 72 65 73 70 65 63  terfaces (respec
38190 74 69 76 65 6c 79 29 3a 0a 2a 2a 0a 2a 2a 20 3c  tively):.**.** <
381a0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20 5b  ul>.**   <li>  [
381b0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
381c0 6c 6f 63 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  loc()] </li>.** 
381d0 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
381e0 5f 6d 75 74 65 78 5f 66 72 65 65 28 29 5d 20 3c  _mutex_free()] <
381f0 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
38200 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
38210 6e 74 65 72 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  nter()] </li>.**
38220 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
38230 33 5f 6d 75 74 65 78 5f 74 72 79 28 29 5d 20 3c  3_mutex_try()] <
38240 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
38250 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
38260 65 61 76 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  eave()] </li>.**
38270 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
38280 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20  3_mutex_held()] 
38290 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
382a0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
382b0 6e 6f 74 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e  notheld()] </li>
382c0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
382d0 2a 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65  * The only diffe
382e0 72 65 6e 63 65 20 69 73 20 74 68 61 74 20 74 68  rence is that th
382f0 65 20 70 75 62 6c 69 63 20 73 71 6c 69 74 65 33  e public sqlite3
38300 5f 58 58 58 20 66 75 6e 63 74 69 6f 6e 73 20 65  _XXX functions e
38310 6e 75 6d 65 72 61 74 65 64 0a 2a 2a 20 61 62 6f  numerated.** abo
38320 76 65 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ve silently igno
38330 72 65 20 61 6e 79 20 69 6e 76 6f 63 61 74 69 6f  re any invocatio
38340 6e 73 20 74 68 61 74 20 70 61 73 73 20 61 20 4e  ns that pass a N
38350 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  ULL pointer inst
38360 65 61 64 0a 2a 2a 20 6f 66 20 61 20 76 61 6c 69  ead.** of a vali
38370 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 2e 20  d mutex handle. 
38380 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
38390 6f 6e 73 20 6f 66 20 74 68 65 20 6d 65 74 68 6f  ons of the metho
383a0 64 73 20 64 65 66 69 6e 65 64 0a 2a 2a 20 62 79  ds defined.** by
383b0 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
383c0 61 72 65 20 6e 6f 74 20 72 65 71 75 69 72 65 64  are not required
383d0 20 74 6f 20 68 61 6e 64 6c 65 20 74 68 69 73 20   to handle this 
383e0 63 61 73 65 2c 20 74 68 65 20 72 65 73 75 6c 74  case, the result
383f0 73 0a 2a 2a 20 6f 66 20 70 61 73 73 69 6e 67 20  s.** of passing 
38400 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
38410 6e 73 74 65 61 64 20 6f 66 20 61 20 76 61 6c 69  nstead of a vali
38420 64 20 6d 75 74 65 78 20 68 61 6e 64 6c 65 20 61  d mutex handle a
38430 72 65 20 75 6e 64 65 66 69 6e 65 64 0a 2a 2a 20  re undefined.** 
38440 28 69 2e 65 2e 20 69 74 20 69 73 20 61 63 63 65  (i.e. it is acce
38450 70 74 61 62 6c 65 20 74 6f 20 70 72 6f 76 69 64  ptable to provid
38460 65 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e an implementat
38470 69 6f 6e 20 74 68 61 74 20 73 65 67 66 61 75 6c  ion that segfaul
38480 74 73 20 69 66 0a 2a 2a 20 69 74 20 69 73 20 70  ts if.** it is p
38490 61 73 73 65 64 20 61 20 4e 55 4c 4c 20 70 6f 69  assed a NULL poi
384a0 6e 74 65 72 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  nter)..**.** The
384b0 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 65   xMutexInit() me
384c0 74 68 6f 64 20 6d 75 73 74 20 62 65 20 74 68 72  thod must be thr
384d0 65 61 64 73 61 66 65 2e 20 20 5e 49 74 20 6d 75  eadsafe.  ^It mu
384e0 73 74 20 62 65 20 68 61 72 6d 6c 65 73 73 20 74  st be harmless t
384f0 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 78 4d 75 74  o.** invoke xMut
38500 65 78 49 6e 69 74 28 29 20 6d 75 74 69 70 6c 65  exInit() mutiple
38510 20 74 69 6d 65 73 20 77 69 74 68 69 6e 20 74 68   times within th
38520 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 20 61  e same process a
38530 6e 64 20 77 69 74 68 6f 75 74 0a 2a 2a 20 69 6e  nd without.** in
38540 74 65 72 76 65 6e 69 6e 67 20 63 61 6c 6c 73 20  tervening calls 
38550 74 6f 20 78 4d 75 74 65 78 45 6e 64 28 29 2e 20  to xMutexEnd(). 
38560 20 53 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   Second and subs
38570 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
38580 2a 2a 20 78 4d 75 74 65 78 49 6e 69 74 28 29 20  ** xMutexInit() 
38590 6d 75 73 74 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a  must be no-ops..
385a0 2a 2a 0a 2a 2a 20 5e 78 4d 75 74 65 78 49 6e 69  **.** ^xMutexIni
385b0 74 28 29 20 6d 75 73 74 20 6e 6f 74 20 75 73 65  t() must not use
385c0 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61   SQLite memory a
385d0 6c 6c 6f 63 61 74 69 6f 6e 20 28 5b 73 71 6c 69  llocation ([sqli
385e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
385f0 20 61 6e 64 20 69 74 73 20 61 73 73 6f 63 69 61   and its associa
38600 74 65 73 29 2e 20 20 5e 53 69 6d 69 6c 61 72 6c  tes).  ^Similarl
38610 79 2c 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29  y, xMutexAlloc()
38620 20 6d 75 73 74 20 6e 6f 74 20 75 73 65 20 53 51   must not use SQ
38630 4c 69 74 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Lite memory.** a
38640 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20  llocation for a 
38650 73 74 61 74 69 63 20 6d 75 74 65 78 2e 20 20 5e  static mutex.  ^
38660 48 6f 77 65 76 65 72 20 78 4d 75 74 65 78 41 6c  However xMutexAl
38670 6c 6f 63 28 29 20 6d 61 79 20 75 73 65 20 53 51  loc() may use SQ
38680 4c 69 74 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  Lite.** memory a
38690 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 61 20  llocation for a 
386a0 66 61 73 74 20 6f 72 20 72 65 63 75 72 73 69 76  fast or recursiv
386b0 65 20 6d 75 74 65 78 2e 0a 2a 2a 0a 2a 2a 20 5e  e mutex..**.** ^
386c0 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
386d0 6b 65 20 74 68 65 20 78 4d 75 74 65 78 45 6e 64  ke the xMutexEnd
386e0 28 29 20 6d 65 74 68 6f 64 20 77 68 65 6e 20 5b  () method when [
386f0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
38700 28 29 5d 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  ()] is.** called
38710 2c 20 62 75 74 20 6f 6e 6c 79 20 69 66 20 74 68  , but only if th
38720 65 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  e prior call to 
38730 78 4d 75 74 65 78 49 6e 69 74 20 72 65 74 75 72  xMutexInit retur
38740 6e 65 64 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a  ned SQLITE_OK..*
38750 2a 20 49 66 20 78 4d 75 74 65 78 49 6e 69 74 20  * If xMutexInit 
38760 66 61 69 6c 73 20 69 6e 20 61 6e 79 20 77 61 79  fails in any way
38770 2c 20 69 74 20 69 73 20 65 78 70 65 63 74 65 64  , it is expected
38780 20 74 6f 20 63 6c 65 61 6e 20 75 70 20 61 66 74   to clean up aft
38790 65 72 20 69 74 73 65 6c 66 0a 2a 2a 20 70 72 69  er itself.** pri
387a0 6f 72 20 74 6f 20 72 65 74 75 72 6e 69 6e 67 2e  or to returning.
387b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
387c0 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
387d0 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
387e0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 3b 0a  _mutex_methods;.
387f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
38800 75 74 65 78 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  utex_methods {. 
38810 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 49 6e 69   int (*xMutexIni
38820 74 29 28 76 6f 69 64 29 3b 0a 20 20 69 6e 74 20  t)(void);.  int 
38830 28 2a 78 4d 75 74 65 78 45 6e 64 29 28 76 6f 69  (*xMutexEnd)(voi
38840 64 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 6d 75  d);.  sqlite3_mu
38850 74 65 78 20 2a 28 2a 78 4d 75 74 65 78 41 6c 6c  tex *(*xMutexAll
38860 6f 63 29 28 69 6e 74 29 3b 0a 20 20 76 6f 69 64  oc)(int);.  void
38870 20 28 2a 78 4d 75 74 65 78 46 72 65 65 29 28 73   (*xMutexFree)(s
38880 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
38890 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65 78  .  void (*xMutex
388a0 45 6e 74 65 72 29 28 73 71 6c 69 74 65 33 5f 6d  Enter)(sqlite3_m
388b0 75 74 65 78 20 2a 29 3b 0a 20 20 69 6e 74 20 28  utex *);.  int (
388c0 2a 78 4d 75 74 65 78 54 72 79 29 28 73 71 6c 69  *xMutexTry)(sqli
388d0 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
388e0 76 6f 69 64