/ Hex Artifact Content
Login

Artifact f9399ee58862fd146eff9725dda83b5c82d04a93:


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 4e 4f 54 20 55 53 45 44 2e 20 44 61 74  /* NOT USED. Dat
42b0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
42c0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
42d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
42e0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
42f0: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4300: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4310: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4320: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4330: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4340: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
4350: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
4360: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
4370: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
4380: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
4390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
43a0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
43b0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
43c0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
43d0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
43e0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
43f0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4400: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4420: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4430: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4440: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4460: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
4470: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
4480: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
4490: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
44a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
44b0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
44c0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
44d0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
44e0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
44f0: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4500: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4510: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4530: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4540: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4550: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4560: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4570: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4580: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4590: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
45a0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
45b0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
45d0: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
45e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
45f0: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4600: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4610: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4620: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4630: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4640: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4650: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4660: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4670: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4680: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4690: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
46a0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
46b0: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
46c0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
46d0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
46e0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
46f0: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4700: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4710: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4720: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4730: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4740: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4750: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4760: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
4770: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4780: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4790: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
47a0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
47b0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
47c0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
47d0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
47e0: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
47f0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4800: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4810: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4820: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4830: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4840: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4850: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4860: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4870: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4880: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4890: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
48a0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
48b0: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
48c0: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
48d0: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
48e0: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
48f0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4900: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4910: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4920: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4930: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4940: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4950: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4960: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4970: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
4980: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
4990: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
49a0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
49b0: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
49c0: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
49d0: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
49e0: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
49f0: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4a00: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4a10: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4a20: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4a30: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4a40: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4a50: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4a60: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
4a70: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
4a80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
4a90: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
4aa0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
4ab0: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
4ac0: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
4ad0: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
4ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
4af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
4b00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
4b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
4b30: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
4b70: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
4bf0: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
4d50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d60: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
4d70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d80: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
4d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4da0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
4db0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4dc0: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
4dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4de0: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
4df0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e00: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
4e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e20: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
4e30: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
4e40: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
4e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4e60: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
4e70: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4e80: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
4e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ea0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
4eb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4ec0: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
4ed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ee0: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
4ef0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4f00: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
4f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
4f20: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
4f30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
4f40: 4b 45 44 20 7c 20 28 31 3c 3c 38 29 20 29 0a 0a  KED | (1<<8) )..
4f50: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4f60: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
4f70: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
4f80: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
4f90: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
4fa0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
4fb0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
4fc0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
4fd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
4fe0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
4ff0: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
5000: 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ter to the xOpen
5010: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a   method of the.*
5020: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  * [sqlite3_vfs] 
5030: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
5040: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5050: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5060: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5070: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5080: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5090: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
50a0: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
50b0: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
50c0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
50d0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
50e0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
50f0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5100: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5110: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5120: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
5140: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
5150: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
5160: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5170: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
5180: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
5190: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
51a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
51c0: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
51d0: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
51e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5200: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
5210: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
5220: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5240: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
5250: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
5260: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5280: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
5290: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
52a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
52c0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
52d0: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
52e0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
5300: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
5310: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
5320: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5340: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
5350: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
5360: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
5380: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
5390: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
53a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
53c0: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
53d0: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
53e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
53f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
5410: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
5420: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
5430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
5460: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5470: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
5480: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5490: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
54a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
54b0: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
54c0: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
54d0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
54e0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 0a 2f 2a 0a 2a  en_v2() */../*.*
54f0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
5500: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
5510: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
5520: 76 69 63 65 43 61 70 61 62 69 6c 69 74 69 65 73  viceCapabilities
5530: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
5540: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
5550: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
5560: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
5570: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
5580: 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a  or of the these.
5590: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
55a0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
55b0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
55c0: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
55d0: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
55e0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
55f0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
5600: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
5610: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
5620: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5630: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
5640: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
5650: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
5660: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
5670: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5680: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
5690: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
56a0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
56b0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
56c0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
56d0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
56e0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
56f0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
5700: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
5710: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
5720: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
5730: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
5740: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
5750: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
5760: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
5770: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
5780: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
5790: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
57a0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
57b0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
57c0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
57d0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
57e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
57f0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
5800: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
5810: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
5820: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
5830: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
5840: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
5850: 72 69 74 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69  rite()..*/.#defi
5860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5870: 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20  ATOMIC          
5880: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69  0x00000001.#defi
5890: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58a0: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20  ATOMIC512       
58b0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
58c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
58d0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
58e0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
58f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5900: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5910: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5920: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5930: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5940: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5950: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5960: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5970: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69  0x00000020.#defi
5980: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5990: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20  ATOMIC16K       
59a0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
59b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59c0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
59d0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
59f0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
5a00: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
5a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a20: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
5a30: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5a50: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
5a60: 30 78 30 30 30 30 30 34 30 30 0a 0a 2f 2a 0a 2a  0x00000400../*.*
5a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5a80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5a90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5aa0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5ab0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5ac0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5ad0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ae0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5af0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5b00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5b10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5b20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5b30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5b50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5b60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5b70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5b90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5ba0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5bb0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5bc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5bd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5be0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5bf0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5c00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5c10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5c20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5c30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5c40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5c50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5c60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5c70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5c80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5c90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ca0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5cb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5cc0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5cd0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ce0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5cf0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5d00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5d10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5d20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5d30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5d40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5d50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5d60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5d70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5d80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5d90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5da0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5db0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5dc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5de0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5df0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
5e00: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
5e10: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
5e20: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
5e30: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
5e50: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
5e60: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
5e70: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
5e80: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
5e90: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
5ea0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
5eb0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
5ec0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
5ed0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
5ee0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
5ef0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
5f00: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
5f10: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
5f20: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
5f30: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
5f40: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
5f50: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
5f60: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
5f70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
5f80: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
5f90: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
5fa0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
5fb0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
5fc0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
5fd0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
5fe0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
5ff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6000: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6010: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6020: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6030: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6040: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6050: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6060: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6070: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6080: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6090: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
60a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
60b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
60c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
60d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
60e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
60f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6100: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6110: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6120: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6130: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6140: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6150: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6160: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6170: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6180: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6190: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
61a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
61b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
61c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
61d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
61e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
61f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6200: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6210: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6220: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6230: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6240: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6250: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6260: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6270: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6280: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6290: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
62a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
62b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
62c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
62d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
62e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
62f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6300: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6310: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6320: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6330: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6340: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6350: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6360: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6370: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6380: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6390: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
63a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
63b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
63c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
63d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
63e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
63f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6400: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6410: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6420: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6430: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6440: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6450: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6460: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6470: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6480: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6490: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
64a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
64b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
64c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
64d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
64e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
64f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6500: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6510: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6520: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6530: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6540: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6550: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6560: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6580: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6590: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
65a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
65c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
65d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
65e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
65f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6600: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6610: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6620: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6630: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6640: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6650: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6660: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6670: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6690: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
66a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
66b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
66c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
66d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
66e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
66f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6700: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6710: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6720: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6730: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6740: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6750: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6760: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6770: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6780: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6790: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
67a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
67b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
67c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
67d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
67e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
67f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6800: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6810: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6820: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6830: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6840: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6850: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6860: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6870: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6880: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6890: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
68a0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
68b0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
68c0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
68d0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
68e0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
68f0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6900: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6910: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6920: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6930: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6940: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6950: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6960: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6970: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6980: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6990: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
69a0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
69b0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
69c0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
69d0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
69e0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
69f0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6a00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6a10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6a20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6a30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6a40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6a50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6a60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6a70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6a80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6a90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6aa0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6ab0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6ac0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6ad0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ae0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6af0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6b00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6b10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6b20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6b30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6b40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6b50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6b60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6b70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6b80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6b90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6ba0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6bb0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6bc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6bd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6be0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6bf0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6c00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6c10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6c20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6c30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6c40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6c60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6c80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6c90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ca0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6cc0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6cd0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ce0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6cf0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6d00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6d10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6d20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6d30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6d40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6d50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6d60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6d70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6d80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6d90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6da0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6db0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6dc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6dd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6de0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6df0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6e00: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6e10: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6e20: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6e30: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6e40: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6e50: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6e60: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6e70: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6e80: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6e90: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6ea0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6eb0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6ec0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6ed0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6ee0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6ef0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6f00: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6f10: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6f20: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6f30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6f40: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6f50: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6f60: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6f70: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6f80: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
6f90: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
6fa0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
6fb0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
6fc0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
6fd0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
6fe0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
6ff0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7000: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7010: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7020: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7030: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7040: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7050: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7060: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7070: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7080: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7090: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
70a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
70b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
70c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
70d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
70e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
70f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7100: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7110: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7120: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7130: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7140: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7150: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7160: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7170: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7180: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7190: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
71a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
71b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
71c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
71d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
71e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
71f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7200: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7210: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7220: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7230: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7240: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7250: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7260: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7270: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7280: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7290: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
72a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
72b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
72c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
72d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
72e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
72f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7300: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7310: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7320: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7330: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7340: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7350: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7360: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7370: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7380: 3b 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  ;.  /* Additiona
7390: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
73a0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
73b0: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
73c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
73d0: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
73e0: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
73f0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
7400: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
7410: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
7420: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
7430: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
7440: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7450: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
7460: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
7470: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
7480: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
7490: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
74a0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
74b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
74c0: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
74d0: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
74e0: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
74f0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
7500: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
7510: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
7520: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
7530: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
7540: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
7550: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
7560: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7570: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
7580: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
7590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
75a0: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
75b0: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
75c0: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
75d0: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
75e0: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
75f0: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
7600: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
7610: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
7620: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
7630: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
7640: 69 6e 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ined..*/.#define
7650: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
7660: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 31  CKSTATE        1
7670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7680: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
7690: 45 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65  E      2.#define
76a0: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
76b0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 33  PROXYFILE      3
76c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
76d0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
76e0: 20 20 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20         4../*.** 
76f0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
7700: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
7710: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
7720: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
7730: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
7740: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
7750: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
7760: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
7770: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
7780: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
7790: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
77a0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
77b0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
77c0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
77d0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
77e0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
77f0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
7800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
7810: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
7820: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
7830: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
7840: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7850: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
7860: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
7870: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7880: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
7890: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
78a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
78b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
78c0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
78d0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
78e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
78f0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
7900: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
7910: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
7920: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
7930: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
7940: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
7950: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 0a  l file system"..
7960: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
7970: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
7980: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
7990: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
79a0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
79b0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
79c0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
79d0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
79e0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
79f0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
7a00: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
7a10: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
7a20: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
7a30: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
7a40: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
7a50: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
7a60: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
7a70: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
7a80: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
7a90: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
7aa0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
7ab0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
7ac0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
7ad0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
7ae0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
7af0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
7b00: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
7b10: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
7b20: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
7b30: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
7b40: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
7b50: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
7b60: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
7b70: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
7b80: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
7b90: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
7ba0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
7bb0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
7bc0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
7bd0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
7be0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
7bf0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
7c00: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
7c10: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
7c20: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
7c30: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
7c40: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
7c50: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
7c60: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
7c70: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
7c80: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
7c90: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
7ca0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
7cb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
7cc0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
7cd0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
7ce0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
7cf0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
7d00: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
7d10: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
7d20: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
7d30: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
7d40: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
7d50: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
7d60: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
7d70: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
7d80: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
7d90: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
7da0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
7db0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
7dc0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
7dd0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
7de0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
7df0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
7e00: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
7e10: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
7e20: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
7e30: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
7e40: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
7e50: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
7e60: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
7e70: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
7e80: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 67  ** SQLite will g
7e90: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
7ea0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
7eb0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
7ec0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
7ed0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
7ee0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
7ef0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
7f00: 61 6d 65 28 29 2e 20 20 53 51 4c 69 74 65 20 66  ame().  SQLite f
7f10: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
7f20: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
7f30: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
7f40: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
7f50: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
7f60: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
7f70: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
7f80: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
7f90: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
7fa0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
7fb0: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
7fc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
7fd0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
7fe0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
7ff0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
8000: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
8010: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
8020: 72 61 6d 65 74 65 72 20 69 73 20 78 4f 70 65 6e  rameter is xOpen
8030: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
8040: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
8050: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
8060: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
8070: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
8080: 2e 20 20 57 68 65 6e 65 76 65 72 20 74 68 65 20  .  Whenever the 
8090: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
80a0: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
80b0: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
80c0: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
80d0: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
80e0: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
80f0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
8100: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
8110: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
8120: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
8130: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
8140: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
8150: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
8160: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
8170: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
8180: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8190: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
81a0: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
81b0: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
81c0: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
81d0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
81e0: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
81f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8200: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
8210: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
8220: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
8230: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
8240: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
8250: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
8260: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
8270: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
8280: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
8290: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
82a0: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
82b0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
82c0: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
82d0: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
82e0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
82f0: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
8300: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8310: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
8320: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
8330: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8340: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
8350: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8360: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
8370: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
8380: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
8390: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
83a0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
83b0: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
83c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
83d0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
83e0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
83f0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
8400: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
8410: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
8420: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
8430: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
8440: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
8450: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
8460: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
8470: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
8480: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
8490: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
84a0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
84b0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
84c0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
84d0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
84e0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
84f0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
8500: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
8510: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
8520: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
8530: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
8540: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
8550: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
8560: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
8570: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
8580: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
8590: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
85a0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
85b0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
85c0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
85d0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
85e0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
85f0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
8600: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
8610: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
8620: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
8630: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
8640: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
8650: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
8660: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
8670: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
8680: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8690: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
86a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
86b0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
86c0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
86d0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
86e0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
86f0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
8700: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
8710: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
8720: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  .  The [SQLITE_O
8730: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
8740: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
8750: 74 20 66 6f 72 20 54 45 4d 50 20 20 64 61 74 61  t for TEMP  data
8760: 62 61 73 65 73 2c 20 6a 6f 75 72 6e 61 6c 73 20  bases, journals 
8770: 61 6e 64 20 66 6f 72 20 73 75 62 6a 6f 75 72 6e  and for subjourn
8780: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  als..**.** The [
8790: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
87a0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
87b0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
87c0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
87d0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
87e0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
87f0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
8800: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
8810: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
8820: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
8830: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
8840: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
8850: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
8860: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
8870: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
8880: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
8890: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
88a0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
88b0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
88c0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
88d0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
88e0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
88f0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
8900: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
8910: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
8920: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
8930: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
8940: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
8950: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
8960: 2e 0a 2a 2a 0a 2a 2a 20 41 74 20 6c 65 61 73 74  ..**.** At least
8970: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
8980: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
8990: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
89a0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
89b0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
89c0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
89d0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
89e0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
89f0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
8a00: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
8a10: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
8a20: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
8a30: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
8a40: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
8a50: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
8a60: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
8a70: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
8a80: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
8a90: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
8aa0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
8ab0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8ac0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
8ad0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
8ae0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
8af0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
8b00: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
8b10: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
8b20: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
8b30: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
8b40: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
8b50: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
8b60: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
8b70: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
8b80: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
8b90: 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  l..**.** The fla
8ba0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
8bb0: 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20  Access() may be 
8bc0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45  [SQLITE_ACCESS_E
8bd0: 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73  XISTS].** to tes
8be0: 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65  t for the existe
8bf0: 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f  nce of a file, o
8c00: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
8c10: 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a  _READWRITE] to.*
8c20: 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  * test whether a
8c30: 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c   file is readabl
8c40: 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20  e and writable, 
8c50: 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
8c60: 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65  S_READ].** to te
8c70: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
8c80: 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65  e is at least re
8c90: 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69  adable.   The fi
8ca0: 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64  le can be a.** d
8cb0: 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20  irectory..**.** 
8cc0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
8cd0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
8ce0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
8cf0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
8d00: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
8d10: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
8d20: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
8d30: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
8d40: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
8d50: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
8d60: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
8d70: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
8d80: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
8d90: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
8da0: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
8db0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
8dc0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
8dd0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
8de0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
8df0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
8e00: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
8e10: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
8e20: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
8e30: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
8e40: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
8e50: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
8e60: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
8e70: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
8e80: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 61  s(), xSleep(), a
8e90: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  nd xCurrentTime(
8ea0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
8eb0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
8ec0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
8ed0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
8ee0: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
8ef0: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
8f00: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
8f10: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
8f20: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
8f30: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
8f40: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
8f50: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
8f60: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
8f70: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
8f80: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
8f90: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
8fa0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
8fb0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
8fc0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
8fd0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
8fe0: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
8ff0: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
9000: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
9010: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
9020: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
9030: 73 20 67 69 76 65 6e 2e 20 20 54 68 65 20 78 43  s given.  The xC
9040: 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20  urrentTime().** 
9050: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
9060: 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62   Julian Day Numb
9070: 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65  er for the curre
9080: 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  nt date and time
9090: 2e 0a 2a 2a 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ..**.*/.typedef 
90a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
90b0: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
90c0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
90d0: 71 6c 69 74 65 33 5f 73 68 6d 20 73 71 6c 69 74  qlite3_shm sqlit
90e0: 65 33 5f 73 68 6d 3b 0a 73 74 72 75 63 74 20 73  e3_shm;.struct s
90f0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
9100: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
9110: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
9120: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
9130: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 32  ber (currently 2
9140: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
9150: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
9160: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
9170: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
9180: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
9190: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
91a0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
91b0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
91c0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
91d0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
91e0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
91f0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
9200: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
9210: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
9220: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
9230: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
9240: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
9250: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
9260: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
9270: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
9280: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
9290: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
92a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
92b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
92c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
92d0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
92e0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
92f0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
9300: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9310: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9320: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
9330: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
9340: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9350: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
9360: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
9370: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
9380: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
9390: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
93a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
93b0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
93c0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
93d0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
93e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
93f0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
9400: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
9410: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9420: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
9430: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
9440: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
9450: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
9460: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
9470: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
9480: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
9490: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
94a0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
94b0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
94c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
94d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
94e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
94f0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
9500: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
9510: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
9520: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
9530: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
9540: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
9550: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
9560: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
9570: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
9580: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
9590: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
95a0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
95b0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
95c0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
95d0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
95e0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
95f0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
9600: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
9610: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
9620: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9630: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
9640: 68 6d 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  hm**);.  int (*x
9650: 53 68 6d 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ShmSize)(sqlite3
9660: 5f 73 68 6d 2a 2c 20 69 6e 74 20 72 65 71 53 69  _shm*, int reqSi
9670: 7a 65 2c 20 69 6e 74 20 2a 70 4e 65 77 53 69 7a  ze, int *pNewSiz
9680: 65 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  e, char**);.  in
9690: 74 20 28 2a 78 53 68 6d 52 65 6c 65 61 73 65 29  t (*xShmRelease)
96a0: 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a 29 3b 0a  (sqlite3_shm*);.
96b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 50 75 73 68    int (*xShmPush
96c0: 29 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a 29 3b  )(sqlite3_shm*);
96d0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 50 75 6c  .  int (*xShmPul
96e0: 6c 29 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a 29  l)(sqlite3_shm*)
96f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
9700: 63 6b 29 28 73 71 6c 69 74 65 33 5f 73 68 6d 2a  ck)(sqlite3_shm*
9710: 2c 20 69 6e 74 20 6c 6f 63 6b 54 79 70 65 2c 20  , int lockType, 
9720: 69 6e 74 20 6f 66 73 74 2c 20 69 6e 74 20 6e 42  int ofst, int nB
9730: 79 74 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  yte);.  int (*xS
9740: 68 6d 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  hmClose)(sqlite3
9750: 5f 73 68 6d 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  _shm*);.  int (*
9760: 78 53 68 6d 44 65 6c 65 74 65 29 28 73 71 6c 69  xShmDelete)(sqli
9770: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
9780: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
9790: 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28 73  int (*xRename)(s
97a0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
97b0: 73 74 20 63 68 61 72 20 2a 7a 4f 6c 64 2c 20 63  st char *zOld, c
97c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 2c  onst char *zNew,
97d0: 20 69 6e 74 20 64 69 72 53 79 6e 63 29 3b 0a 20   int dirSync);. 
97e0: 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
97f0: 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65  imeInt64)(sqlite
9800: 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f  3_vfs*, sqlite3_
9810: 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20  int64*);.  /*.  
9820: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
9830: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
9840: 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20  ions 1 and 2 of 
9850: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
9860: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
9870: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
9880: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
9890: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
98a0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
98b0: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
98c0: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
98d0: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
98e0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
98f0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
9900: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
9910: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
9920: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
9930: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
9940: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
9950: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
9960: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
9970: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
9980: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
9990: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
99a0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
99b0: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
99c0: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
99d0: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
99e0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
99f0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
9a00: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
9a10: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
9a20: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
9a30: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
9a40: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
9a50: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
9a60: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
9a70: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
9a80: 69 6c 65 20 69 73 20 62 6f 74 68 20 72 65 61 64  ile is both read
9a90: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
9aa0: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
9ab0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
9ac0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
9ad0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
9ae0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
9af0: 72 65 61 64 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65  readable..*/.#de
9b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
9b10: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
9b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
9b30: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
9b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9b50: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
9b60: 20 32 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   2../*.** CAPI3R
9b70: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
9b80: 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d  e xShmLock VFS m
9b90: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
9ba0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
9bb0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
9bc0: 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
9bd0: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
9be0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
9bf0: 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
9c00: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
9c10: 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
9c20: 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6c 6f   the specific lo
9c30: 63 6b 69 6e 67 20 61 63 74 69 6f 6e 2e 20 20 45  cking action.  E
9c40: 78 61 63 74 6c 79 20 6f 6e 65 20 6f 66 20 74 68  xactly one of th
9c50: 65 20 66 69 72 73 74 20 74 68 72 65 65 0a 2a 2a  e first three.**
9c60: 20 76 61 6c 75 65 73 20 6d 75 73 74 20 62 65 20   values must be 
9c70: 75 73 65 64 20 69 6e 69 20 74 68 65 20 6c 6f 63  used ini the loc
9c80: 6b 54 79 70 65 20 70 61 72 61 6d 65 74 65 72 2e  kType parameter.
9c90: 20 20 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20    The fourth.** 
9ca0: 76 61 6c 75 65 20 28 53 51 4c 49 54 45 5f 53 48  value (SQLITE_SH
9cb0: 4d 5f 42 4c 4f 43 4b 29 20 63 61 6e 20 6f 70 74  M_BLOCK) can opt
9cc0: 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20  ionally be ORed 
9cd0: 69 6e 74 6f 20 74 68 65 20 6c 6f 63 6b 54 79 70  into the lockTyp
9ce0: 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  e.** parameter t
9cf0: 6f 20 63 61 75 73 65 20 74 68 65 20 74 68 72 65  o cause the thre
9d00: 61 64 20 74 6f 20 62 6c 6f 63 6b 20 75 6e 74 69  ad to block unti
9d10: 6c 20 74 68 65 20 6c 6f 63 6b 20 62 65 63 6f 6d  l the lock becom
9d20: 65 73 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e  es.** available.
9d30: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
9d40: 54 45 5f 53 48 4d 5f 52 44 4c 4b 20 20 20 30 78  TE_SHM_RDLK   0x
9d50: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
9d60: 45 5f 53 48 4d 5f 57 52 4c 4b 20 20 20 30 78 30  E_SHM_WRLK   0x0
9d70: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
9d80: 5f 53 48 4d 5f 55 4e 4c 4b 20 20 20 30 78 30 34  _SHM_UNLK   0x04
9d90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9da0: 53 48 4d 5f 42 4c 4f 43 4b 20 20 30 78 30 38 0a  SHM_BLOCK  0x08.
9db0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9dc0: 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20   Initialize The 
9dd0: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
9de0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
9df0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
9e00: 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a  outine initializ
9e10: 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  es the.** SQLite
9e20: 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20   library.  ^The 
9e30: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
9e40: 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65  () routine.** de
9e50: 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65  allocates any re
9e60: 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72  sources that wer
9e70: 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
9e80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
9e90: 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e()..** These ro
9ea0: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67  utines are desig
9eb0: 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72  ned to aid in pr
9ec0: 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61  ocess initializa
9ed0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74  tion and.** shut
9ee0: 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64  down on embedded
9ef0: 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73   systems.  Works
9f00: 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69  tation applicati
9f10: 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ons using.** SQL
9f20: 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20  ite normally do 
9f30: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f  not need to invo
9f40: 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65  ke either of the
9f50: 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
9f60: 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
9f70: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
9f80: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
9f90: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
9fa0: 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74  s.** the first t
9fb0: 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ime sqlite3_init
9fc0: 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
9fd0: 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c  ked during the l
9fe0: 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68  ifetime of.** th
9ff0: 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  e process, or if
a000: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
a010: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
a020: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
a030: 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  voked.** followi
a040: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ng a call to sql
a050: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
a060: 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65    ^(Only an effe
a070: 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66  ctive call.** of
a080: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a090: 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69  ize() does any i
a0a0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20  nitialization.  
a0b0: 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a  All other calls.
a0c0: 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  ** are harmless 
a0d0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
a0e0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
a0f0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20  3_shutdown() is 
a100: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
a110: 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65  all if it is the
a120: 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74   first.** call t
a130: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
a140: 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c  wn() since the l
a150: 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ast sqlite3_init
a160: 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c  ialize().  ^(Onl
a170: 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76  y.** an effectiv
a180: 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
a190: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65  3_shutdown() doe
a1a0: 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69  s any deinitiali
a1b0: 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f  zation..** All o
a1c0: 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73  ther valid calls
a1d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
a1e0: 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c  down() are harml
a1f0: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
a200: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
a210: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74  initialize() int
a220: 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64  erface is thread
a230: 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65  safe, but sqlite
a240: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
a250: 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c  is not.  The sql
a260: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
a270: 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f  interface must o
a280: 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72  nly be called fr
a290: 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74  om a.** single t
a2a0: 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e  hread.  All open
a2b0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
a2c0: 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20  ctions] must be 
a2d0: 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a  closed and all.*
a2e0: 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72  * other SQLite r
a2f0: 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65  esources must be
a300: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69   deallocated pri
a310: 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a  or to invoking.*
a320: 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  * sqlite3_shutdo
a330: 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e  wn()..**.** Amon
a340: 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20  g other things, 
a350: 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  ^sqlite3_initial
a360: 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b  ize() will invok
a370: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  e.** sqlite3_os_
a380: 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72  init().  Similar
a390: 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75  ly, ^sqlite3_shu
a3a0: 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20  tdown().** will 
a3b0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f  invoke sqlite3_o
a3c0: 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  s_end()..**.** ^
a3d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
a3e0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
a3f0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a400: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e  _OK] on success.
a410: 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65  .** ^If for some
a420: 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33   reason, sqlite3
a430: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
a440: 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69   unable to initi
a450: 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62  alize.** the lib
a460: 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74  rary (perhaps it
a470: 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
a480: 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20  locate a needed 
a490: 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a  resource such.**
a4a0: 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20   as a mutex) it 
a4b0: 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f  returns an [erro
a4c0: 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68  r code] other th
a4d0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  an [SQLITE_OK]..
a4e0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
a4f0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a500: 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
a510: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20  d internally by 
a520: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51  many other.** SQ
a530: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
a540: 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69  so that an appli
a550: 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64  cation usually d
a560: 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a  oes not need to.
a570: 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
a580: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
a590: 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78  irectly.  For ex
a5a0: 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f  ample, [sqlite3_
a5b0: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73  open()].** calls
a5c0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a5d0: 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c  ize() so the SQL
a5e0: 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
a5f0: 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
a600: 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64  y.** initialized
a610: 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f   when [sqlite3_o
a620: 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  pen()] is called
a630: 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62   if it has not b
a640: 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a  e initialized.**
a650: 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65   already.  ^Howe
a660: 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69  ver, if SQLite i
a670: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
a680: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  the [SQLITE_OMIT
a690: 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f  _AUTOINIT].** co
a6a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
a6b0: 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f  n, then the auto
a6c0: 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73  matic calls to s
a6d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
a6e0: 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74  e().** are omitt
a6f0: 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ed and the appli
a700: 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c  cation must call
a710: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
a720: 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a  ize() directly.*
a730: 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  * prior to using
a740: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
a750: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f  e interface.  Fo
a760: 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62  r maximum portab
a770: 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20  ility,.** it is 
a780: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
a790: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c   applications al
a7a0: 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69  ways invoke sqli
a7b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a7c0: 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69  .** directly pri
a7d0: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
a7e0: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
a7f0: 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20  erface.  Future 
a800: 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53  releases.** of S
a810: 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72  QLite may requir
a820: 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65  e this.  In othe
a830: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68  r words, the beh
a840: 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a  avior exhibited.
a850: 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
a860: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
a870: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
a880: 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63  OINIT] might bec
a890: 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75  ome the.** defau
a8a0: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73  lt behavior in s
a8b0: 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
a8c0: 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  se of SQLite..**
a8d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
a8e0: 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e  os_init() routin
a8f0: 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67  e does operating
a900: 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
a910: 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  .** initializati
a920: 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65  on of the SQLite
a930: 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73   library.  The s
a940: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
a950: 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65  ** routine undoe
a960: 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20  s the effect of 
a970: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
a980: 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b  ).  Typical task
a990: 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62  s.** performed b
a9a0: 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  y these routines
a9b0: 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74   include allocat
a9c0: 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74  ion or deallocat
a9d0: 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63  ion.** of static
a9e0: 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74   resources, init
a9f0: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c  ialization of gl
aa00: 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a  obal variables,.
aa10: 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20  ** setting up a 
aa20: 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
aa30: 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72  _vfs] module, or
aa40: 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61   setting up.** a
aa50: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
aa60: 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71  ration using [sq
aa70: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e  lite3_config()].
aa80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
aa90: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
aaa0: 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65  ver invoke eithe
aab0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
aac0: 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
aad0: 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63  3_os_end() direc
aae0: 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63  tly.  The applic
aaf0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c  ation should onl
ab00: 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  y invoke.** sqli
ab10: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ab20: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75   and sqlite3_shu
ab30: 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71  tdown().  The sq
ab40: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
ab50: 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
ab60: 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63  called automatic
ab70: 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
ab80: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
ab90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  .** sqlite3_os_e
aba0: 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62  nd() is called b
abb0: 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  y sqlite3_shutdo
abc0: 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61  wn().  Appropria
abd0: 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  te.** implementa
abe0: 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65  tions for sqlite
abf0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
ac00: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ac10: 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e  .** are built in
ac20: 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69  to SQLite when i
ac30: 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  t is compiled fo
ac40: 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c  r Unix, Windows,
ac50: 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65   or OS/2..** Whe
ac60: 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73  n [custom builds
ac70: 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68   | built for oth
ac80: 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a  er platforms].**
ac90: 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c   (using the [SQL
aca0: 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20  ITE_OS_OTHER=1] 
acb0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
acc0: 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c  option) the appl
acd0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70  ication must sup
ace0: 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69  ply a suitable i
acf0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  mplementation fo
ad00: 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  r.** sqlite3_os_
ad10: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
ad20: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e  e3_os_end().  An
ad30: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70   application-sup
ad40: 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65  plied.** impleme
ad50: 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
ad60: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20  e3_os_init() or 
ad70: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
ad80: 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20  .** must return 
ad90: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
ada0: 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20  uccess and some 
adb0: 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64  other [error cod
adc0: 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75  e] upon.** failu
add0: 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  re..*/.int sqlit
ade0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
adf0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
ae00: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
ae10: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
ae20: 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20  init(void);.int 
ae30: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76  sqlite3_os_end(v
ae40: 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  oid);../*.** CAP
ae50: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69  I3REF: Configuri
ae60: 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69  ng The SQLite Li
ae70: 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20  brary.**.** The 
ae80: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ae90: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
aea0: 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61  ed to make globa
aeb0: 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  l configuration.
aec0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51  ** changes to SQ
aed0: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
aee0: 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20   tune SQLite to 
aef0: 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
af00: 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  ds of.** the app
af10: 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64  lication.  The d
af20: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61  efault configura
af30: 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e  tion is recommen
af40: 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20  ded for most.** 
af50: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64  applications and
af60: 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   so this routine
af70: 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20   is usually not 
af80: 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69  necessary.  It i
af90: 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f  s.** provided to
afa0: 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70   support rare ap
afb0: 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20  plications with 
afc0: 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a  unusual needs..*
afd0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
afe0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
aff0: 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ace is not threa
b000: 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c  dsafe.  The appl
b010: 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  ication.** must 
b020: 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f  insure that no o
b030: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
b040: 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b  rfaces are invok
b050: 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74  ed by other.** t
b060: 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c  hreads while sql
b070: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
b080: 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68   running.  Furth
b090: 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f  ermore, sqlite3_
b0a0: 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20  config().** may 
b0b0: 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
b0c0: 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
b0d0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
b0e0: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
b0f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
b100: 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
b110: 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
b120: 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
b130: 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
b140: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
b150: 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
b160: 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
b170: 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
b180: 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
b190: 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
b1a0: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
b1b0: 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
b1c0: 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
b1d0: 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
b1e0: 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
b1f0: 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
b200: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
b210: 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
b220: 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
b230: 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
b240: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
b250: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
b260: 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
b270: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r.** [SQLITE_CON
b280: 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
b290: 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
b2a0: 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
b2b0: 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
b2c0: 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
b2d0: 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
b2e0: 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
b2f0: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
b300: 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
b310: 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   on the [SQLITE_
b320: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
b330: 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  EAD | configurat
b340: 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69  ion option].** i
b350: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
b360: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65  ment..**.** ^Whe
b370: 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  n a configuratio
b380: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c  n option is set,
b390: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
b3a0: 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ) returns [SQLIT
b3b0: 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  E_OK]..** ^If th
b3c0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e  e option is unkn
b3d0: 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73  own or SQLite is
b3e0: 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74   unable to set t
b3f0: 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65  he option.** the
b400: 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  n this routine r
b410: 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72  eturns a non-zer
b420: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  o [error code]..
b430: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
b440: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
b450: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b460: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
b470: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
b480: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
b490: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
b4a0: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
b4b0: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
b4c0: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
b4d0: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
b4e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
b4f0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
b500: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
b510: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
b520: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
b530: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
b540: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
b550: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
b560: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
b570: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
b580: 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73  ment).  The.** s
b590: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
b5a0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f  () interface sho
b5b0: 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  uld only be used
b5c0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
b5d0: 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  er.** the databa
b5e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
b5f0: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
b600: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
b610: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
b620: 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  n16()], or [sqli
b630: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
b640: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f   .**.** The seco
b650: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
b660: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
b670: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
b680: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
b690: 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74  on verb - an int
b6a0: 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 69  eger code that i
b6b0: 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a  ndicates what.**
b6c0: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
b6d0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b6e0: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
b6f0: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65  nfigured..** The
b700: 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72   only choice for
b710: 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b   this value is [
b720: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
b730: 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e  LOOKASIDE]..** N
b740: 65 77 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b  ew verbs are lik
b750: 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64 20  ely to be added 
b760: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
b770: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
b780: 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   Additional argu
b790: 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20  ments depend on 
b7a0: 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  the verb..**.** 
b7b0: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
b7c0: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
b7d0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
b7e0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
b7f0: 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
b800: 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
b810: 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
b820: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
b830: 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
b840: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
b850: 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
b860: 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
b870: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
b880: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
b890: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
b8a0: 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
b8b0: 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
b8c0: 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
b8d0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
b8e0: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
b8f0: 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
b900: 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
b910: 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
b920: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
b930: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
b940: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
b950: 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
b960: 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
b970: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
b980: 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
b990: 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
b9a0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
b9b0: 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
b9c0: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
b9d0: 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
b9e0: 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
b9f0: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
ba00: 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
ba10: 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
ba20: 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
ba30: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
ba40: 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
ba50: 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
ba60: 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
ba70: 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
ba80: 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
ba90: 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
baa0: 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
bab0: 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
bac0: 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
bad0: 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
bae0: 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
baf0: 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
bb00: 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
bb10: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
bb20: 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
bb30: 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
bb40: 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
bb50: 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
bb60: 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
bb70: 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
bb80: 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
bb90: 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
bba0: 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
bbb0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
bbc0: 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
bbd0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
bbe0: 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
bbf0: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
bc00: 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
bc10: 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
bc20: 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
bc30: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
bc40: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
bc50: 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
bc60: 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
bc70: 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
bc80: 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
bc90: 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
bca0: 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
bcb0: 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
bcc0: 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
bcd0: 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
bce0: 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20 78  he xMalloc and x
bcf0: 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
bd00: 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
bd10: 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ** malloc() and 
bd20: 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
bd30: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
bd40: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
bd50: 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d 65   The xRealloc me
bd60: 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20 6c  thod must work l
bd70: 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20 66 72  ike realloc() fr
bd80: 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
bd90: 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69 74  C library.** wit
bda0: 68 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e 20  h the exception 
bdb0: 74 68 61 74 20 69 66 20 74 68 65 20 73 65 63 6f  that if the seco
bdc0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  nd argument to x
bdd0: 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f 2c  Realloc is zero,
bde0: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75 73  .** xRealloc mus
bdf0: 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20 69  t be a no-op - i
be00: 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72 66 6f  t must not perfo
be10: 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69 6f  rm any allocatio
be20: 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  n or.** dealloca
be30: 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65 20 67  tion.  ^SQLite g
be40: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
be50: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
be60: 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
be70: 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
be80: 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
be90: 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
bea0: 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e 64  xRoundup..** And
beb0: 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77 68 65   so in cases whe
bec0: 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c 77 61  re xRoundup alwa
bed0: 79 73 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73  ys returns a pos
bee0: 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a 2a  itive number,.**
bef0: 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70 65   xRealloc can pe
bf00: 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20 61 73  rform exactly as
bf10: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69   the standard li
bf20: 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28 29 20  brary realloc() 
bf30: 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65 20  and.** still be 
bf40: 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77 69  in compliance wi
bf50: 74 68 20 74 68 69 73 20 73 70 65 63 69 66 69 63  th this specific
bf60: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  ation..**.** xSi
bf70: 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
bf80: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
bf90: 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
bfa0: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
bfb0: 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
bfc0: 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
bfd0: 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
bfe0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
bff0: 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
c000: 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
c010: 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
c020: 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
c030: 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
c040: 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
c050: 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
c060: 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
c070: 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
c080: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c090: 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
c0a0: 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
c0b0: 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
c0c0: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
c0d0: 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
c0e0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
c0f0: 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
c100: 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
c110: 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
c120: 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
c130: 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
c140: 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
c150: 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
c160: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
c170: 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
c180: 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
c190: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
c1a0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
c1b0: 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
c1c0: 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
c1d0: 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
c1e0: 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
c1f0: 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
c200: 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
c210: 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
c220: 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
c230: 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
c240: 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
c250: 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46  y allocator.  (F
c260: 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
c270: 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
c280: 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
c290: 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
c2a0: 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
c2b0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
c2c0: 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
c2d0: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
c2e0: 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
c2f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
c300: 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
c310: 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
c320: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
c330: 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
c340: 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
c350: 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
c360: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
c370: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
c380: 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
c390: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
c3a0: 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
c3b0: 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
c3c0: 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
c3d0: 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
c3e0: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
c3f0: 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
c400: 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
c410: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
c420: 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
c430: 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
c440: 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
c450: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
c460: 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
c470: 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
c480: 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
c490: 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
c4a0: 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
c4b0: 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
c4c0: 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
c4d0: 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
c4e0: 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
c4f0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
c500: 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
c510: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
c520: 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
c530: 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
c540: 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
c550: 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
c560: 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
c570: 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
c580: 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
c590: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
c5a0: 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
c5b0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
c5c0: 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
c5d0: 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
c5e0: 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
c5f0: 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
c600: 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
c610: 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
c620: 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
c630: 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
c640: 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
c650: 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
c660: 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
c670: 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
c680: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c690: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
c6a0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
c6b0: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
c6c0: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
c6d0: 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
c6e0: 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
c6f0: 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
c700: 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
c710: 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
c720: 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
c730: 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
c740: 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
c750: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
c760: 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
c770: 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
c780: 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
c790: 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
c7a0: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
c7b0: 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
c7c0: 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
c7d0: 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
c7e0: 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
c7f0: 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
c800: 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
c810: 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
c820: 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
c830: 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
c840: 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
c850: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
c860: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
c870: 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
c880: 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
c890: 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
c8a0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
c8b0: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
c8c0: 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
c8d0: 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
c8e0: 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
c8f0: 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
c900: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
c910: 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
c920: 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
c930: 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
c940: 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
c950: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
c960: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
c970: 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
c980: 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
c990: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
c9a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
c9b0: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
c9c0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
c9d0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
c9e0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
c9f0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
ca00: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
ca10: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
ca20: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
ca30: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
ca40: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
ca50: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
ca60: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
ca70: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
ca80: 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
ca90: 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
caa0: 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
cab0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
cac0: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
cad0: 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
cae0: 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
caf0: 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
cb00: 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
cb10: 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
cb20: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
cb30: 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
cb40: 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
cb50: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
cb60: 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
cb70: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
cb80: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
cb90: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
cba0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
cbb0: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
cbc0: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
cbd0: 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
cbe0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
cbf0: 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
cc00: 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
cc10: 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
cc20: 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
cc30: 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
cc40: 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
cc50: 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
cc60: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
cc70: 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
cc80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
cc90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
cca0: 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
ccb0: 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
ccc0: 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
ccd0: 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
cce0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
ccf0: 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
cd00: 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
cd10: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
cd20: 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
cd30: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
cd40: 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
cd50: 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
cd60: 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
cd70: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
cd80: 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
cd90: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
cda0: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
cdb0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
cdc0: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
cdd0: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
cde0: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
cdf0: 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
ce00: 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
ce10: 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
ce20: 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
ce30: 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
ce40: 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
ce50: 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
ce60: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
ce70: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
ce80: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
ce90: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
cea0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
ceb0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
cec0: 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
ced0: 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
cee0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
cef0: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
cf00: 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
cf10: 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
cf20: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
cf30: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
cf40: 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
cf50: 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
cf60: 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
cf70: 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
cf80: 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
cf90: 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
cfa0: 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
cfb0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
cfc0: 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
cfd0: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
cfe0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
cff0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
d000: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
d010: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
d020: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
d030: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
d040: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
d050: 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
d060: 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
d070: 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
d080: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d090: 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
d0a0: 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
d0b0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
d0c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
d0d0: 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
d0e0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
d0f0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
d100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
d110: 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
d120: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
d130: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
d140: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
d150: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
d160: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
d170: 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
d180: 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
d190: 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
d1a0: 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
d1b0: 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
d1c0: 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
d1d0: 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
d1e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d1f0: 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
d200: 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
d210: 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
d220: 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
d230: 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
d240: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
d250: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
d260: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
d270: 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
d280: 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
d290: 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
d2a0: 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
d2b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
d2c0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
d2d0: 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
d2e0: 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
d2f0: 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
d300: 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
d310: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d320: 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
d330: 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
d340: 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
d350: 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
d360: 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
d370: 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
d380: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
d390: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
d3a0: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
d3b0: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
d3c0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
d3d0: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
d3e0: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
d3f0: 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
d400: 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
d410: 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
d420: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
d430: 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
d440: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
d450: 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
d460: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
d470: 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
d480: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
d490: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d4a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
d4b0: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
d4c0: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
d4d0: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
d4e0: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
d4f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
d500: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
d510: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
d520: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
d530: 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  e.  The argument
d540: 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
d550: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
d560: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
d570: 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
d580: 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
d590: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
d5a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
d5b0: 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
d5c0: 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
d5d0: 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
d5e0: 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
d5f0: 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
d600: 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
d610: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
d620: 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
d630: 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
d640: 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
d650: 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
d660: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
d670: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
d680: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
d690: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
d6a0: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
d6b0: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
d6c0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
d6d0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
d6e0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
d6f0: 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
d700: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
d710: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
d720: 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
d730: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
d740: 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
d750: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
d760: 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
d770: 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
d780: 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
d790: 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
d7a0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
d7b0: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
d7c0: 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
d7d0: 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
d7e0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
d7f0: 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
d800: 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
d810: 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
d820: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
d830: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
d840: 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
d850: 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
d860: 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
d870: 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
d880: 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
d890: 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
d8a0: 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
d8b0: 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
d8c0: 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
d8d0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
d8e0: 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
d8f0: 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
d900: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
d910: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
d920: 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
d930: 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
d940: 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
d950: 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
d960: 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
d970: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
d980: 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
d990: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
d9a0: 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
d9b0: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
d9c0: 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
d9d0: 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  t()].**   <li> [
d9e0: 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
d9f0: 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
da00: 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
da10: 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
da20: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
da30: 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
da40: 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
da50: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
da60: 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
da70: 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
da80: 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
da90: 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
daa0: 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
dab0: 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
dac0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
dad0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
dae0: 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
daf0: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
db00: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
db10: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
db20: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
db30: 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61   use for.** scra
db40: 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65  tch memory.  The
db50: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
db60: 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74  uments:  A point
db70: 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  er an 8-byte.** 
db80: 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62  aligned memory b
db90: 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68  uffer from which
dba0: 20 74 68 65 20 73 63 72 61 63 68 20 61 6c 6c 6f   the scrach allo
dbb0: 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
dbc0: 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
dbd0: 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
dbe0: 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
dbf0: 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
dc00: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
dc10: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
dc20: 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
dc30: 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
dc40: 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
dc50: 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20 70   of 16. The sz p
dc60: 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20  arameter should 
dc70: 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a 2a  be a few bytes.*
dc80: 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68  * larger than th
dc90: 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63 68  e actual scratch
dca0: 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
dcb0: 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c 20  due to internal 
dcc0: 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68 65  overhead..** The
dcd0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
dce0: 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
dcf0: 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
dd00: 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
dd10: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
dd20: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
dd30: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
dd40: 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74  ll use no more t
dd50: 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20  han one scratch 
dd60: 62 75 66 66 65 72 20 70 65 72 20 74 68 72 65 61  buffer per threa
dd70: 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75  d.  So.** N shou
dd80: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68 65  ld be set to the
dd90: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
dda0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
ddb0: 61 64 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ads.  ^SQLite wi
ddc0: 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 72 65 71 75  ll.** never requ
ddd0: 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75  ire a scratch bu
dde0: 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
ddf0: 65 20 74 68 61 6e 20 36 20 74 69 6d 65 73 20 74  e than 6 times t
de00: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 70  he database.** p
de10: 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51  age size. ^If SQ
de20: 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
de30: 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 63 72 61   additional scra
de40: 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
de50: 64 20 0a 2a 2a 20 77 68 61 74 20 69 73 20 70 72  d .** what is pr
de60: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
de70: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
de80: 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
de90: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
dea0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
deb0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
dec0: 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
ded0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
dee0: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
def0: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
df00: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
df10: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
df20: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
df30: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
df40: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
df50: 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
df60: 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
df70: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
df80: 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  emenation.  .** 
df90: 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
dfa0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
dfb0: 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
dfc0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
dfd0: 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
dfe0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
dff0: 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
e000: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
e010: 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  ACHE option..** 
e020: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
e030: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
e040: 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e  s option: A poin
e050: 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c  ter to 8-byte al
e060: 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c  igned.** memory,
e070: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
e080: 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73  h page buffer (s
e090: 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
e0a0: 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e  er of pages (N).
e0b0: 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
e0c0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
e0d0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
e0e0: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
e0f0: 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
e100: 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
e110: 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c  12 and 32768) pl
e120: 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72  us a little extr
e130: 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  a for each.** pa
e140: 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
e150: 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a   page header siz
e160: 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79  e is 20 to 40 by
e170: 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  tes depending on
e180: 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63  .** the host arc
e190: 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20  hitecture.  ^It 
e1a0: 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
e1b0: 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
e1c0: 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f  ed memory,.** to
e1d0: 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c   make sz a littl
e1e0: 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68  e too large.  Th
e1f0: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
e200: 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
e210: 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
e220: 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
e230: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
e240: 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
e250: 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
e260: 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
e270: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
e280: 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
e290: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
e2a0: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
e2b0: 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
e2c0: 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e  dds to cache.  ^
e2d0: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
e2e0: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
e2f0: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
e300: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
e310: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
e320: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
e330: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
e340: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
e350: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
e360: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
e370: 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65  .** ^The impleme
e380: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75 73  ntation might us
e390: 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  e one or more of
e3a0: 20 74 68 65 20 4e 20 62 75 66 66 65 72 73 20 74   the N buffers t
e3b0: 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f 72  o hold .** memor
e3c0: 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e 66  y accounting inf
e3d0: 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70 6f  ormation. The po
e3e0: 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69 72  inter in the fir
e3f0: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
e400: 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74  .** be aligned t
e410: 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
e420: 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
e430: 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
e440: 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65  QLite.** will be
e450: 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e   undefined.</dd>
e460: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
e470: 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
e480: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
e490: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
e4a0: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
e4b0: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
e4c0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
e4d0: 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
e4e0: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
e4f0: 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
e500: 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
e510: 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
e520: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
e530: 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
e540: 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
e550: 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
e560: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
e570: 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
e580: 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
e590: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
e5a0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
e5b0: 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
e5c0: 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
e5d0: 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
e5e0: 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
e5f0: 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
e600: 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
e610: 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
e620: 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
e630: 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
e640: 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
e650: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
e660: 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
e670: 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
e680: 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
e690: 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
e6a0: 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
e6b0: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
e6c0: 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
e6d0: 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
e6e0: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68  ot NULL and eith
e6f0: 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
e700: 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a  E_MEMSYS3] or.**
e710: 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
e720: 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66  MEMSYS5] are def
e730: 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61  ined, then the a
e740: 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
e750: 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
e760: 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
e770: 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
e780: 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
e790: 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
e7a0: 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
e7b0: 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
e7c0: 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
e7d0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
e7e0: 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
e7f0: 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
e800: 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
e810: 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
e820: 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  d.</dd>.**.** <d
e830: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
e840: 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
e850: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
e860: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
e870: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
e880: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
e890: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
e8a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
e8b0: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
e8c0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
e8d0: 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
e8e0: 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
e8f0: 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
e900: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
e910: 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
e920: 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
e930: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
e940: 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
e950: 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
e960: 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
e970: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
e980: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
e990: 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
e9a0: 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
e9b0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e9c0: 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
e9d0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
e9e0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
e9f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
ea00: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
ea10: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
ea20: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
ea30: 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
ea40: 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
ea50: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
ea60: 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
ea70: 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
ea80: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ea90: 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
eaa0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
eab0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
eac0: 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
ead0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
eae0: 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
eaf0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
eb00: 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
eb10: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
eb20: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
eb30: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
eb40: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
eb50: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
eb60: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
eb70: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
eb80: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
eb90: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
eba0: 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
ebb0: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
ebc0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
ebd0: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
ebe0: 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
ebf0: 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
ec00: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
ec10: 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
ec20: 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
ec30: 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
ec40: 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
ec50: 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
ec60: 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
ec70: 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
ec80: 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
ec90: 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
eca0: 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
ecb0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
ecc0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
ecd0: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
ece0: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
ecf0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
ed00: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
ed10: 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
ed20: 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
ed30: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
ed40: 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
ed50: 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
ed60: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
ed70: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
ed80: 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
ed90: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
eda0: 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
edb0: 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
edc0: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
edd0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
ede0: 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
edf0: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
ee00: 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
ee10: 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
ee20: 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
ee30: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
ee40: 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
ee50: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
ee60: 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
ee70: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
ee80: 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
ee90: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
eea0: 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
eeb0: 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
eec0: 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
eed0: 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
eee0: 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
eef0: 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
ef00: 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
ef10: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
ef20: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
ef30: 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
ef40: 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
ef50: 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
ef60: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
ef70: 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
ef80: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
ef90: 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
efa0: 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
efb0: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
efc0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
efd0: 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
efe0: 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
eff0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f000: 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c  E_CONFIG_PCACHE<
f010: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
f020: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
f030: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
f040: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
f050: 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b  inter to.** an [
f060: 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
f070: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20  ethods] object. 
f080: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65   This object spe
f090: 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72  cifies the inter
f0a0: 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73  face.** to a cus
f0b0: 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69  tom page cache i
f0c0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e  mplementation.)^
f0d0: 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
f0e0: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
f0f0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73   object and uses
f100: 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63   it for page cac
f110: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
f120: 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  tions.</dd>.**.*
f130: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
f140: 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64  FIG_GETPCACHE</d
f150: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
f160: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
f170: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
f180: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
f190: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
f1a0: 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
f1b0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53  hods] object.  S
f1c0: 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20  QLite copies of 
f1d0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70  the current.** p
f1e0: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
f1f0: 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68  entation into th
f200: 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64  at object.)^ </d
f210: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
f220: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f  ITE_CONFIG_LOG</
f230: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
f240: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
f250: 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OG option takes 
f260: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61  two arguments: a
f270: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a   pointer to a.**
f280: 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
f290: 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20   call signature 
f2a0: 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  of void(*)(void*
f2b0: 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
f2c0: 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69  ), .** and a poi
f2d0: 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49  nter to void. ^I
f2e0: 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  f the function p
f2f0: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
f300: 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76  LL, it is.** inv
f310: 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oked by [sqlite3
f320: 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65  _log()] to proce
f330: 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20  ss each logging 
f340: 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
f350: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  ** function poin
f360: 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ter is NULL, the
f370: 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
f380: 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d   interface becom
f390: 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e  es a no-op..** ^
f3a0: 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72  The void pointer
f3b0: 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63   that is the sec
f3c0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
f3d0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
f3e0: 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  G is.** passed t
f3f0: 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69  hrough as the fi
f400: 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
f410: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f420: 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
f430: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e  ** function when
f440: 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69  ever that functi
f450: 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  on is invoked.  
f460: 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
f470: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
f480: 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20  logger function 
f490: 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
f4a0: 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
f4b0: 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f   to the correspo
f4c0: 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  nding.** [sqlite
f4d0: 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e  3_log()] call an
f4e0: 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f  d is intended to
f4f0: 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f   be a [result co
f500: 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78  de] or an.** [ex
f510: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
f520: 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64  de].  ^The third
f530: 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65   parameter passe
f540: 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20  d to the logger 
f550: 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67  is.** log messag
f560: 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69  e after formatti
f570: 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f  ng via [sqlite3_
f580: 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20  snprintf()]..** 
f590: 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69  The SQLite loggi
f5a0: 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ng interface is 
f5b0: 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74  not reentrant; t
f5c0: 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
f5d0: 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62  on.** supplied b
f5e0: 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
f5f0: 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b  n must not invok
f600: 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
f610: 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20  erface..** In a 
f620: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61  multi-threaded a
f630: 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20  pplication, the 
f640: 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
f650: 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
f660: 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74  nction must be t
f670: 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e  hreadsafe. </dd>
f680: 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
f690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
f6a0: 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
f6b0: 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
f6c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f6d0: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
f6e0: 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
f6f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f700: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
f710: 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
f720: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f730: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
f740: 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
f750: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
f760: 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
f770: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
f780: 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
f790: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
f7a0: 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
f7b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
f7c0: 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
f7d0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
f7e0: 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
f7f0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
f800: 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
f810: 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
f820: 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
f830: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f840: 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
f850: 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
f860: 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
f870: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f880: 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
f890: 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
f8a0: 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
f8b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
f8c0: 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
f8d0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
f8e0: 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
f8f0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
f900: 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
f910: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
f920: 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
f930: 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
f940: 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
f950: 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
f960: 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
f970: 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
f980: 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
f990: 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
f9a0: 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
f9b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
f9c0: 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
f9d0: 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
f9e0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
f9f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
fa00: 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
fa10: 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  5  /* sqlite3_pc
fa20: 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
fa30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
fa40: 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20  CONFIG_LOG      
fa50: 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63      16  /* xFunc
fa60: 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a  , void* */../*.*
fa70: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
fa80: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
fa90: 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
faa0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
fab0: 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
fac0: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
fad0: 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
fae0: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
faf0: 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
fb00: 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
fb10: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
fb20: 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
fb30: 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
fb40: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
fb50: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
fb60: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
fb70: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
fb80: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
fb90: 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
fba0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
fbb0: 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
fbc0: 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
fbd0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
fbe0: 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
fbf0: 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
fc00: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
fc10: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
fc20: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
fc30: 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
fc40: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
fc50: 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
fc60: 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
fc70: 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
fc80: 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
fc90: 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
fca0: 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
fcb0: 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
fcc0: 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
fcd0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
fce0: 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
fcf0: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
fd00: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
fd10: 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
fd20: 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
fd30: 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
fd40: 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
fd50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
fd60: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
fd70: 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
fd80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
fd90: 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
fda0: 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
fdb0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
fdc0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
fdd0: 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
fde0: 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79 20  er to an memory 
fdf0: 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
fe00: 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
fe10: 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
fe20: 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
fe30: 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
fe40: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
fe50: 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
fe60: 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
fe70: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
fe80: 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
fe90: 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
fea0: 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
feb0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
fec0: 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
fed0: 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
fee0: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
fef0: 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
ff00: 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
ff10: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
ff20: 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
ff30: 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
ff40: 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
ff50: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
ff60: 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
ff70: 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
ff80: 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
ff90: 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
ffa0: 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
ffb0: 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
ffc0: 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
ffd0: 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
ffe0: 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
fff0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
10000 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
10010 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
10020 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
10030 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
10040 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
10050 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
10060 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a 2a  e next smaller.*
10070 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  * multiple of 8.
10080 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
10090 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
100a0 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  SIDE]</dd>.**.**
100b0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
100c0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
100d0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
100e0 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
100f0 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a  t int */.../*.**
10100 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
10110 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
10120 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
10130 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
10140 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
10150 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
10160 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
10170 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
10180 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
10190 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
101a0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
101b0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
101c0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
101d0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
101e0 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
101f0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
10200 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
10210 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
10220 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
10230 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
10240 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
10250 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
10260 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20  .** ^Each entry 
10270 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62  in an SQLite tab
10280 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20  le has a unique 
10290 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a  64-bit signed.**
102a0 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c   integer key cal
102b0 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c  led the [ROWID |
102c0 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20   "rowid"]. ^The 
102d0 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20  rowid is always 
102e0 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20  available.** as 
102f0 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f  an undeclared co
10300 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44  lumn named ROWID
10310 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44  , OID, or _ROWID
10320 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f  _ as long as tho
10330 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20  se.** names are 
10340 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79  not also used by
10350 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
10360 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49  ared columns. ^I
10370 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68  f.** the table h
10380 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  as a column of t
10390 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49  ype [INTEGER PRI
103a0 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74  MARY KEY] then t
103b0 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  hat column.** is
103c0 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66   another alias f
103d0 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a  or the rowid..**
103e0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
103f0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
10400 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73  owid] of the mos
10410 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63  t recent.** succ
10420 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
10430 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
10440 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61  e from the [data
10450 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10460 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
10470 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
10480 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
10490 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
104a0 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
104b0 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
104c0 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
104d0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
104e0 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
104f0 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
10500 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68 65  n a trigger, the
10510 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
10520 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
10530 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64   row is returned
10540 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
10550 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
10560 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69  trigger is runni
10570 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
10580 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72 6d  the trigger term
10590 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75  inates, the valu
105a0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
105b0 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65  is routine.** re
105c0 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73  verts to the las
105d0 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64  t value inserted
105e0 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
105f0 67 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a  ger fired.)^.**.
10600 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
10610 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
10620 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
10630 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
10640 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
10650 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
10660 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
10670 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
10680 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
10690 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
106a0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
106b0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
106c0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
106d0 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
106e0 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
106f0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
10700 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
10710 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
10720 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
10730 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
10740 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
10750 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
10760 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
10770 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
10780 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
10790 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
107a0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
107b0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
107c0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
107d0 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
107e0 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
107f0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
10800 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
10810 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
10820 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
10830 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
10840 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
10850 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
10860 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
10870 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
10880 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
10890 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
108a0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
108b0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
108c0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
108d0 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
108e0 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
108f0 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
10900 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
10910 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
10920 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
10930 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
10940 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
10950 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
10960 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
10970 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
10980 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
10990 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
109a0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
109b0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
109c0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
109d0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
109e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
109f0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
10a00 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
10a10 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
10a20 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
10a30 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
10a40 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
10a50 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
10a60 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
10a70 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  wid]..*/.sqlite3
10a80 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
10a90 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
10aa0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
10ab0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
10ac0 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
10ad0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
10ae0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
10af0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
10b00 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
10b10 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
10b20 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
10b30 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
10b40 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
10b50 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
10b60 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
10b70 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
10b80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10b90 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
10ba0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
10bb0 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
10bc0 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
10bd0 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
10be0 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
10bf0 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
10c00 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
10c10 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
10c20 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
10c30 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
10c40 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
10c50 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
10c60 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
10c70 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
10c80 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
10c90 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
10ca0 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
10cb0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
10cc0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
10cd0 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
10ce0 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
10cf0 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
10d00 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
10d10 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
10d20 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
10d30 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
10d40 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
10d50 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
10d60 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
10d70 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
10d80 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
10d90 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
10da0 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
10db0 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
10dc0 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
10dd0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
10de0 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
10df0 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
10e00 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
10e10 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
10e20 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
10e30 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
10e40 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
10e50 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
10e60 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
10e70 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
10e80 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
10e90 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
10ea0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
10eb0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
10ec0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
10ed0 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
10ee0 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
10ef0 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
10f00 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
10f10 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
10f20 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
10f30 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
10f40 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
10f50 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
10f60 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
10f70 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
10f80 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
10f90 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
10fa0 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
10fb0 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
10fc0 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
10fd0 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
10fe0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
10ff0 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
11000 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
11010 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
11020 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
11030 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
11040 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
11050 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
11060 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
11070 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
11080 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
11090 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
110a0 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
110b0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
110c0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
110d0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
110e0 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
110f0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
11100 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
11110 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
11120 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
11130 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
11140 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
11150 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
11160 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
11170 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
11180 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
11190 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
111a0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
111b0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
111c0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
111d0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
111e0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
111f0 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
11200 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
11210 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
11220 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
11230 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
11240 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
11250 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
11260 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
11270 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
11280 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
11290 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
112a0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
112b0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
112c0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
112d0 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
112e0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
112f0 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
11300 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
11310 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
11320 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
11330 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
11340 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
11350 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
11360 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
11370 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
11380 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
11390 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
113a0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
113b0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
113c0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
113d0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
113e0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
113f0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
11400 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
11410 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
11420 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
11430 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
11440 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
11450 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
11460 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
11470 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
11480 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
11490 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  int sqlite3_chan
114a0 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  ges(sqlite3*);..
114b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
114c0 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20  Total Number Of 
114d0 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a  Rows Modified.**
114e0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
114f0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
11500 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61  umber of row cha
11510 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
11520 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44  INSERT],.** [UPD
11530 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
11540 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63   statements sinc
11550 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
11560 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20  connection] was 
11570 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65  opened..** ^(The
11580 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20   count returned 
11590 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  by sqlite3_total
115a0 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75  _changes() inclu
115b0 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a  des all changes.
115c0 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45  ** from all [CRE
115d0 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
115e0 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20  igger] contexts 
115f0 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65  and changes made
11600 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20   by.** [foreign 
11610 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f  key actions]. Ho
11620 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f  wever,.** the co
11630 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
11640 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65  lude changes use
11650 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b  d to implement [
11660 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
11670 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c  ints,.** do roll
11680 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70  backs or ABORT p
11690 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44  rocessing, or [D
116a0 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65  ROP TABLE] proce
116b0 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63  ssing.  The.** c
116c0 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
116d0 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69  clude rows of vi
116e0 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e  ews that fire an
116f0 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
11700 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68  gger],.** though
11710 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20   if the INSTEAD 
11720 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73  OF trigger makes
11730 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20   changes of its 
11740 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67  own, those chang
11750 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74  es .** are count
11760 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71  ed.)^.** ^The sq
11770 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
11780 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ges() function c
11790 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65  ounts the change
117a0 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20  s as soon as.** 
117b0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68  the statement th
117c0 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73  at makes them is
117d0 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e   completed (when
117e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
117f0 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73  andle.** is pass
11800 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ed to [sqlite3_r
11810 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
11820 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29  te3_finalize()])
11830 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
11840 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
11850 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
11860 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
11870 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
11880 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
11890 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
118a0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
118b0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
118c0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
118d0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
118e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
118f0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
11900 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
11910 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
11920 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
11930 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
11940 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
11950 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
11960 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
11970 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
11980 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
11990 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
119a0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
119b0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
119c0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
119d0 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
119e0 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
119f0 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
11a00 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
11a10 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
11a20 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
11a30 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
11a40 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
11a50 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
11a60 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
11a70 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
11a80 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
11a90 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
11aa0 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
11ab0 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
11ac0 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
11ad0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
11ae0 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
11af0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
11b00 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
11b10 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
11b20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
11b30 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
11b40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
11b50 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
11b60 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
11b70 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
11b80 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
11b90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11ba0 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
11bb0 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
11bc0 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
11bd0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
11be0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
11bf0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
11c00 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
11c10 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
11c20 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
11c30 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
11c40 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
11c50 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
11c60 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
11c70 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
11c80 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
11c90 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
11ca0 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
11cb0 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
11cc0 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
11cd0 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
11ce0 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
11cf0 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
11d00 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
11d10 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
11d20 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
11d30 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
11d40 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
11d50 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
11d60 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
11d70 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
11d80 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
11d90 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
11da0 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
11db0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
11dc0 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
11dd0 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
11de0 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
11df0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
11e00 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
11e10 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11e20 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
11e30 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
11e40 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
11e50 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
11e60 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
11e70 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
11e80 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
11e90 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
11ea0 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
11eb0 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
11ec0 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
11ed0 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
11ee0 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
11ef0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
11f00 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
11f10 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
11f20 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
11f30 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
11f40 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
11f50 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
11f60 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
11f70 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
11f80 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
11f90 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
11fa0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
11fb0 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
11fc0 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
11fd0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
11fe0 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
11ff0 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
12000 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
12010 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
12020 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
12030 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
12040 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
12050 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
12060 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
12070 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
12080 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
12090 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
120a0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
120b0 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
120c0 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
120d0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e  .void sqlite3_in
120e0 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a  terrupt(sqlite3*
120f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
12100 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
12110 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
12120 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a  t Is Complete.**
12130 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
12140 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75  es are useful du
12150 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e  ring command-lin
12160 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72  e input to deter
12170 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63  mine if the.** c
12180 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64  urrently entered
12190 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66   text seems to f
121a0 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  orm a complete S
121b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a  QL statement or.
121c0 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c  ** if additional
121d0 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64   input is needed
121e0 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20   before sending 
121f0 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a  the text into.**
12200 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73   SQLite for pars
12210 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ing.  ^These rou
12220 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69  tines return 1 i
12230 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
12240 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f  ng.** appears to
12250 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53   be a complete S
12260 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  QL statement.  ^
12270 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a  A statement is j
12280 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63  udged to be.** c
12290 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e  omplete if it en
122a0 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f  ds with a semico
122b0 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73  lon token and is
122c0 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66   not a prefix of
122d0 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65   a.** well-forme
122e0 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52  d CREATE TRIGGER
122f0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65   statement.  ^Se
12300 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72  micolons that ar
12310 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69  e embedded withi
12320 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65  n.** string lite
12330 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69  rals or quoted i
12340 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20  dentifier names 
12350 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20  or comments are 
12360 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65  not.** independe
12370 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20  nt tokens (they 
12380 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20  are part of the 
12390 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74  token in which t
123a0 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64  hey are.** embed
123b0 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f  ded) and thus do
123c0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20   not count as a 
123d0 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e  statement termin
123e0 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61  ator.  ^Whitespa
123f0 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e  ce.** and commen
12400 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74  ts that follow t
12410 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c  he final semicol
12420 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a  on are ignored..
12430 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
12440 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69  tines return 0 i
12450 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
12460 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20  is incomplete.  
12470 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ^If a.** memory 
12480 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
12490 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f  , then SQLITE_NO
124a0 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  MEM is returned.
124b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
124c0 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61  utines do not pa
124d0 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74  rse the SQL stat
124e0 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77  ements thus.** w
124f0 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73  ill not detect s
12500 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63  yntactically inc
12510 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a  orrect SQL..**.*
12520 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61  * ^(If SQLite ha
12530 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69  s not been initi
12540 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71  alized using [sq
12550 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12560 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f  ()] prior .** to
12570 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65   invoking sqlite
12580 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74  3_complete16() t
12590 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  hen sqlite3_init
125a0 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f  ialize() is invo
125b0 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  ked.** automatic
125c0 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f  ally by sqlite3_
125d0 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49  complete16().  I
125e0 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a  f that initializ
125f0 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20  ation fails,.** 
12600 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20  then the return 
12610 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
12620 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
12630 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f  will be non-zero
12640 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f  .** regardless o
12650 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
12660 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69   the input SQL i
12670 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a  s complete.)^.**
12680 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
12690 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
126a0 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  te()] must be a 
126b0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
126c0 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e  ** UTF-8 string.
126d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
126e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
126f0 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20  plete16()] must 
12700 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
12710 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
12720 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20  tring in native 
12730 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69  byte order..*/.i
12740 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
12750 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
12760 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  sql);.int sqlite
12770 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e  3_complete16(con
12780 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a  st void *sql);..
12790 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
127a0 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62  Register A Callb
127b0 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51  ack To Handle SQ
127c0 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73  LITE_BUSY Errors
127d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
127e0 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c  tine sets a call
127f0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68  back function th
12800 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
12810 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  ked whenever.** 
12820 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
12830 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74  de to open a dat
12840 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74  abase table that
12850 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
12860 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
12870 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20  s locked..**.** 
12880 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
12890 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74  lback is NULL, t
128a0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  hen [SQLITE_BUSY
128b0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
128c0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69  RR_BLOCKED].** i
128d0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
128e0 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
128f0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
12900 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
12910 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
12920 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
12930 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
12940 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
12950 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
12960 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
12970 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
12980 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
12990 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
129a0 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
129b0 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
129c0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
129d0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
129e0 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
129f0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
12a00 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
12a10 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
12a20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
12a30 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
12a40 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
12a50 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66  * been invoked f
12a60 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20  or this locking 
12a70 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
12a80 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
12a90 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
12aa0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
12ab0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
12ac0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
12ad0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
12ae0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
12af0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
12b00 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e  OCKED] is return
12b10 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  ed..** ^If the c
12b20 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
12b30 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
12b40 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
12b50 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  * is made to ope
12b60 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
12b70 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74  or reading and t
12b80 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
12b90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
12ba0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
12bb0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
12bc0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
12bd0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
12be0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
12bf0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
12c00 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
12c10 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
12c20 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
12c30 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
12c40 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
12c50 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
12c60 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
12c70 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
12c80 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ].** or [SQLITE_
12c90 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69  IOERR_BLOCKED] i
12ca0 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69  nstead of invoki
12cb0 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ng the busy hand
12cc0 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72  ler..** Consider
12cd0 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72   a scenario wher
12ce0 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73  e one process is
12cf0 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20   holding a read 
12d00 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20  lock that.** it 
12d10 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f  is trying to pro
12d20 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76  mote to a reserv
12d30 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61  ed lock and.** a
12d40 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
12d50 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73  is holding a res
12d60 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20  erved lock that 
12d70 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20  it is trying.** 
12d80 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e  to promote to an
12d90 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e   exclusive lock.
12da0 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63    The first proc
12db0 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65  ess cannot proce
12dc0 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74  ed.** because it
12dd0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
12de0 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
12df0 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  e second process
12e00 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65   cannot.** proce
12e10 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ed because it is
12e20 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
12e30 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20  first.  If both 
12e40 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76  processes.** inv
12e50 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e  oke the busy han
12e60 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77  dlers, neither w
12e70 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f  ill make any pro
12e80 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72  gress.  Therefor
12e90 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74  e,.** SQLite ret
12ea0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53  urns [SQLITE_BUS
12eb0 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  Y] for the first
12ec0 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67   process, hoping
12ed0 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69   that this.** wi
12ee0 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69  ll induce the fi
12ef0 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72  rst process to r
12f00 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20  elease its read 
12f10 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a  lock and allow.*
12f20 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  * the second pro
12f30 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e  cess to proceed.
12f40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
12f50 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63  ult busy callbac
12f60 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  k is NULL..**.**
12f70 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55   ^The [SQLITE_BU
12f80 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e  SY] error is con
12f90 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54  verted to [SQLIT
12fa0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
12fb0 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
12fc0 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  is in the middle
12fd0 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e   of a large tran
12fe0 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c  saction where al
12ff0 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73  l the.** changes
13000 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e   will not fit in
13010 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  to the in-memory
13020 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20   cache.  SQLite 
13030 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20  will.** already 
13040 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20  hold a RESERVED 
13050 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61  lock on the data
13060 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69  base file, but i
13070 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72  t needs.** to pr
13080 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20  omote this lock 
13090 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20  to EXCLUSIVE so 
130a0 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c  that it can spil
130b0 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73  l cache.** pages
130c0 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
130d0 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20  se file without 
130e0 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65  harm to concurre
130f0 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20  nt.** readers.  
13100 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65  ^If it is unable
13110 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20   to promote the 
13120 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69  lock, then the i
13130 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68  n-memory.** cach
13140 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69  e will be left i
13150 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e  n an inconsisten
13160 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74  t state and so t
13170 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65  he error.** code
13180 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f   is promoted fro
13190 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79  m the relatively
131a0 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f   benign [SQLITE_
131b0 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20  BUSY] to.** the 
131c0 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c  more severe [SQL
131d0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
131e0 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72  D].  ^This error
131f0 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a   code promotion.
13200 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74  ** forces an aut
13210 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20  omatic rollback 
13220 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20  of the changes. 
13230 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68   See the.** <a h
13240 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69  ref="/cvstrac/wi
13250 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46  ki?p=CorruptionF
13260 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
13270 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f  r">.** Corruptio
13280 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
13290 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67  ror</a> wiki pag
132a0 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69  e for a discussi
132b0 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69  on of why.** thi
132c0 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a  s is important..
132d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
132e0 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
132f0 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
13300 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
13310 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13320 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
13330 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
13340 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
13350 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
13360 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
13370 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
13380 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
13390 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77  _timeout()].** w
133a0 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20  ill also set or 
133b0 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68  clear the busy h
133c0 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  andler..**.** Th
133d0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
133e0 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20  should not take 
133f0 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63  any actions whic
13400 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20  h modify the.** 
13410 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13420 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
13430 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
13440 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74  r.  Any such act
13450 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69  ions.** result i
13460 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
13470 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62  vior..** .** A b
13480 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74  usy handler must
13490 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64   not close the d
134a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
134b0 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72  on.** or [prepar
134c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
134d0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
134e0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a  usy handler..*/.
134f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
13500 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
13510 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
13520 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
13530 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
13540 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
13550 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
13560 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
13570 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
13580 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
13590 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
135a0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
135b0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
135c0 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
135d0 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
135e0 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
135f0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
13600 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
13610 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
13620 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
13630 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
13640 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
13650 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
13660 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
13670 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
13680 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
13690 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
136a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
136b0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
136c0 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
136d0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
136e0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
136f0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
13700 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
13710 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
13720 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
13730 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
13740 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
13750 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
13760 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
13770 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
13780 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
13790 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
137a0 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
137b0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
137c0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
137d0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
137e0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
137f0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
13800 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
13810 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
13820 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
13830 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
13840 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
13850 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
13860 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
13870 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
13880 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
13890 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
138a0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
138b0 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66 69  eries.**.** Defi
138c0 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
138d0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
138e0 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
138f0 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
13900 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
13910 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
13920 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
13930 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
13940 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
13950 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
13960 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
13970 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
13980 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
13990 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
139a0 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
139b0 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
139c0 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
139d0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
139e0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
139f0 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
13a00 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
13a10 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
13a20 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
13a30 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
13a40 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
13a50 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
13a60 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
13a70 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
13a80 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
13a90 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
13aa0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
13ab0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
13ac0 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
13ad0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
13ae0 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
13af0 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
13b00 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
13b10 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
13b20 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
13b30 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
13b40 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
13b50 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
13b60 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
13b70 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
13b80 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
13b90 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
13ba0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
13bb0 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
13bc0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
13bd0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
13be0 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
13bf0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
13c00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
13c10 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
13c20 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
13c30 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
13c40 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
13c50 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
13c60 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
13c70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
13c80 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
13c90 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
13ca0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
13cb0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
13cc0 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
13cd0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
13ce0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73 20  le()]..**.** As 
13cf0 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
13d00 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
13d10 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
13d20 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
13d30 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
13d40 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
13d50 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
13d60 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
13d70 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
13d80 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
13d90 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
13da0 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
13db0 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
13dc0 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
13dd0 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
13de0 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
13df0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
13e00 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
13e10 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
13e20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
13e30 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
13e40 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
13e50 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
13e60 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
13e70 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
13e80 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
13e90 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
13ea0 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
13eb0 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
13ec0 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
13ed0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
13ee0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
13ef0 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
13f00 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
13f10 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
13f20 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
13f30 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
13f40 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
13f50 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
13f60 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
13f70 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
13f80 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
13f90 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
13fa0 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
13fb0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
13fc0 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
13fd0 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
13fe0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
13ff0 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
14000 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
14010 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
14020 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
14030 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
14040 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
14050 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
14060 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
14070 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
14080 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
14090 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
140a0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
140b0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
140c0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
140d0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
140e0 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
140f0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
14100 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
14110 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
14120 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
14130 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
14140 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
14150 20 73 68 6f 75 6c 64 20 70 61 73 73 20 74 68 65   should pass the
14160 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
14170 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
14180 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
14190 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
141a0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
141b0 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
141c0 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
141d0 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
141e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
141f0 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
14200 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
14210 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
14220 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
14230 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
14240 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
14250 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
14260 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
14270 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
14280 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
14290 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
142a0 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
142b0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
142c0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
142d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
142e0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
142f0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
14300 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
14310 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
14320 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
14330 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
14340 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
14350 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
14360 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
14370 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
14380 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
14390 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
143a0 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
143b0 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
143c0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
143d0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
143e0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
143f0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
14400 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
14410 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
14420 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
14430 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
14440 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
14450 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
14460 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 29 5e  te3_errmsg()].)^
14470 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
14480 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
14490 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
144a0 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
144b0 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
144c0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
144d0 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
144e0 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
144f0 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
14500 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
14510 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
14520 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
14530 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
14540 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
14550 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
14560 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
14570 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
14580 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
14590 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
145a0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
145b0 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
145c0 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
145d0 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64   here */.);.void
145e0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
145f0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
14600 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
14610 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
14620 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
14630 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
14640 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
14650 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
14660 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
14670 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
14680 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
14690 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
146a0 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ry..**.** ^The s
146b0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
146c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70   and sqlite3_vmp
146d0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73  rintf() routines
146e0 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20   write their.** 
146f0 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d  results into mem
14700 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
14710 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
14720 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72  c()]..** The str
14730 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
14740 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69   these two routi
14750 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  nes should be.**
14760 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71   released by [sq
14770 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20  lite3_free()].  
14780 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72  ^Both routines r
14790 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20  eturn a.** NULL 
147a0 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69  pointer if [sqli
147b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73  te3_malloc()] is
147c0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
147d0 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65  ate enough.** me
147e0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
147f0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
14800 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73 71  g..**.** ^(In sq
14810 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
14820 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69   routine is simi
14830 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66  lar to "snprintf
14840 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ()" from.** the 
14850 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
14860 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  ry.  The result 
14870 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  is written into 
14880 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75  the.** buffer su
14890 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65  pplied as the se
148a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77  cond parameter w
148b0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76  hose size is giv
148c0 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72  en by.** the fir
148d0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f  st parameter. No
148e0 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65  te that the orde
148f0 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73  r of the.** firs
14900 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73  t two parameters
14910 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f   is reversed fro
14920 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20  m snprintf().)^ 
14930 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68   This is an.** h
14940 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65  istorical accide
14950 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62  nt that cannot b
14960 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20  e fixed without 
14970 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b  breaking.** back
14980 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
14990 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73  ity.  ^(Note als
149a0 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73  o that sqlite3_s
149b0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74  nprintf().** ret
149c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
149d0 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73  o its buffer ins
149e0 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62  tead of the numb
149f0 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74  er of.** charact
14a00 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69  ers actually wri
14a10 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75  tten into the bu
14a20 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69  ffer.)^  We admi
14a30 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75  t that.** the nu
14a40 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
14a50 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64  rs written would
14a60 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75   be a more usefu
14a70 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  l return.** valu
14a80 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20  e but we cannot 
14a90 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65  change the imple
14aa0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
14ab0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
14ac0 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62  ** now without b
14ad0 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62  reaking compatib
14ae0 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73  ility..**.** ^As
14af0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66   long as the buf
14b00 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61  fer size is grea
14b10 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73  ter than zero, s
14b20 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
14b30 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20  ).** guarantees 
14b40 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20  that the buffer 
14b50 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  is always zero-t
14b60 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
14b70 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
14b80 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74  ter "n" is the t
14b90 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
14ba0 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69   buffer, includi
14bb0 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20  ng space for.** 
14bc0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
14bd0 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e  tor.  So the lon
14be0 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74  gest string that
14bf0 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65   can be complete
14c00 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69  ly.** written wi
14c10 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63  ll be n-1 charac
14c20 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ters..**.** Thes
14c30 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
14c40 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
14c50 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
14c60 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
14c70 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
14c80 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
14c90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
14ca0 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
14cb0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
14cc0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
14cd0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
14ce0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
14cf0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
14d00 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
14d10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
14d20 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
14d30 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
14d40 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
14d50 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a  null-terminated.
14d60 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
14d70 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
14d80 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
14d90 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
14da0 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
14db0 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
14dc0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
14dd0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
14de0 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
14df0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
14e00 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
14e10 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
14e20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
14e30 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
14e40 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
14e50 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
14e60 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
14e70 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
14e80 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
14e90 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
14ea0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
14eb0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
14ec0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
14ed0 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
14ee0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
14ef0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
14f00 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
14f10 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
14f20 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
14f30 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
14f40 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
14f50 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
14f60 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
14f70 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
14f80 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
14f90 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
14fa0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
14fb0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
14fc0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
14fd0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
14fe0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
14ff0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
15000 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
15010 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
15020 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
15030 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
15040 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
15050 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
15060 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
15070 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
15080 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
15090 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
150a0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
150b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
150c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
150d0 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
150e0 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
150f0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
15100 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
15110 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
15120 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
15130 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
15140 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
15150 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
15160 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
15170 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
15180 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
15190 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
151a0 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
151b0 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
151c0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
151d0 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
151e0 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
151f0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
15200 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
15210 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
15220 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
15230 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
15240 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
15250 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
15260 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
15270 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
15280 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
15290 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
152a0 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
152b0 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
152c0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
152d0 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
152e0 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
152f0 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
15300 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
15310 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
15320 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
15330 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
15340 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
15350 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
15360 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
15370 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
15380 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
15390 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
153a0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
153b0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
153c0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
153d0 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
153e0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
153f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
15400 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
15410 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
15420 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
15430 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
15440 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
15450 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
15460 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
15470 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
15480 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
15490 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
154a0 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
154b0 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
154c0 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
154d0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
154e0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
154f0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
15500 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
15510 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
15520 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
15530 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
15540 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
15550 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
15560 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
15570 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
15580 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
15590 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
155a0 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
155b0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
155c0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
155d0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
155e0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
155f0 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
15600 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
15610 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
15620 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
15630 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
15640 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
15650 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
15660 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
15670 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
15680 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
15690 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
156a0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
156b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
156c0 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
156d0 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
156e0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
156f0 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
15700 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
15710 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
15720 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
15730 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
15740 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
15750 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
15760 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
15770 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
15780 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
15790 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
157a0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
157b0 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
157c0 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
157d0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
157e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
157f0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
15800 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
15810 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
15820 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
15830 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
15840 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
15850 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
15860 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
15870 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
15880 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
15890 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
158a0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
158b0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
158c0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
158d0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
158e0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
158f0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
15900 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
15910 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
15920 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
15930 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
15940 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
15950 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
15960 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
15970 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
15980 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
15990 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
159a0 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
159b0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
159c0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
159d0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
159e0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
159f0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
15a00 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
15a10 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
15a20 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
15a30 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
15a40 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
15a50 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
15a60 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
15a70 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
15a80 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
15a90 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
15aa0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
15ab0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
15ac0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
15ad0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
15ae0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
15af0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lloc()..**.** ^(
15b00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
15b10 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
15b20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
15b30 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
15b40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15b50 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
15b60 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
15b70 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
15b80 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
15b90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15ba0 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
15bb0 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
15bc0 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20   parameter.)^ ^ 
15bd0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
15be0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
15bf0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
15c00 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
15c10 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
15c20 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
15c30 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
15c40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
15c50 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
15c60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15c70 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
15c80 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  oc()..** ^If the
15c90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
15ca0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
15cb0 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
15cc0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
15cd0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
15ce0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
15cf0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
15d00 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
15d10 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
15d20 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
15d30 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
15d40 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  loc()..** ^sqlit
15d50 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
15d60 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
15d70 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
15d80 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
15d90 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
15da0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
15db0 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
15dc0 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
15dd0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
15de0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
15df0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
15e00 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
15e10 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
15e20 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
15e30 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
15e40 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
15e50 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
15e60 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
15e70 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
15e80 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
15e90 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
15ea0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
15eb0 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
15ec0 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
15ed0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
15ee0 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
15ef0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
15f00 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
15f10 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
15f20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
15f30 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
15f40 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
15f50 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
15f60 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20  ndary..**.** In 
15f70 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
15f80 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
15f90 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
15fa0 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
15fb0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
15fc0 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
15fd0 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
15fe0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
15ff0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
16000 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
16010 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
16020 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
16030 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
16040 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
16050 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
16060 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
16070 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
16080 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  The Windows OS i
16090 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
160a0 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73 74  alls.** the syst
160b0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
160c0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
160d0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
160e0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
160f0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
16100 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
16110 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
16120 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
16130 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
16140 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
16150 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
16160 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
16170 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
16180 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63 74  rrors are detect
16190 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
161a0 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  are reported bac
161b0 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
161c0 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
161d0 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
161e0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
161f0 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
16200 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
16210 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
16220 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
16230 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
16240 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
16250 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
16260 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
16270 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
16280 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
16290 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
162a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
162b0 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
162c0 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
162d0 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
162e0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
162f0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
16300 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
16310 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
16320 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
16330 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
16340 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
16350 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
16360 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
16370 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20  loc()]..*/.void 
16380 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
16390 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
163a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
163b0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
163c0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
163d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
163e0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
163f0 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
16400 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
16410 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
16420 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
16430 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
16440 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
16450 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16460 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
16470 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
16480 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
16490 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
164a0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
164b0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
164c0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
164d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
164e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
164f0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
16500 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
16510 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
16520 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
16530 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
16540 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
16550 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
16560 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
16570 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
16580 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
16590 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
165a0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
165b0 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
165c0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
165d0 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
165e0 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
165f0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
16600 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
16610 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
16620 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
16630 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
16640 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
16650 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
16660 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
16670 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
16680 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
16690 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
166a0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
166b0 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
166c0 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
166d0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
166e0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
166f0 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
16700 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
16710 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
16720 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
16730 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
16740 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
16750 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
16760 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
16770 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
16780 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
16790 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
167a0 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
167b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
167c0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
167d0 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
167e0 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
167f0 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
16800 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73   the reset..*/.s
16810 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
16820 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
16830 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f  (void);.sqlite3_
16840 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
16850 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
16860 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
16870 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16880 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
16890 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
168a0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
168b0 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
168c0 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
168d0 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
168e0 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
168f0 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
16900 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
16910 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
16920 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
16930 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
16940 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
16950 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
16960 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
16970 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
16980 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
16990 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
169a0 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
169b0 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
169c0 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
169d0 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
169e0 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
169f0 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
16a00 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
16a10 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
16a20 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
16a30 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
16a40 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
16a50 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
16a60 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
16a70 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69   time this routi
16a80 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65  ne is invoked (e
16a90 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79  ither internally
16aa0 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70   or by.** the ap
16ab0 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50  plication) the P
16ac0 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73  RNG is seeded us
16ad0 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f  ing randomness o
16ae0 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
16af0 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
16b00 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65  method of the de
16b10 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
16b20 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  fs] object..** ^
16b30 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e  On all subsequen
16b40 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74  t invocations, t
16b50 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  he pseudo-random
16b60 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65  ness is generate
16b70 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20  d.** internally 
16b80 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f  and without reco
16b90 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c  urse to the [sql
16ba0 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f  ite3_vfs] xRando
16bb0 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e  mness.** method.
16bc0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
16bd0 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
16be0 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
16bf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
16c00 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
16c10 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
16c20 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ks.**.** ^This r
16c30 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
16c40 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   a authorizer ca
16c50 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
16c60 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
16c70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16c80 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
16c90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16ca0 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
16cb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
16cc0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
16cd0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
16ce0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
16cf0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
16d00 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
16d10 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
16d20 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
16d30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
16d40 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
16d50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
16d60 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
16d70 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
16d80 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
16d90 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
16da0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
16db0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
16dc0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
16dd0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
16de0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16df0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
16e00 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
16e10 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
16e20 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
16e30 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
16e40 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
16e50 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
16e60 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
16e70 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
16e80 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
16e90 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
16ea0 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
16eb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
16ec0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
16ed0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
16ee0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
16ef0 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
16f00 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
16f10 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
16f20 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
16f30 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
16f40 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
16f50 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
16f60 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
16f70 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
16f80 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
16f90 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
16fa0 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
16fb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
16fc0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
16fd0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
16fe0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
16ff0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
17000 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
17010 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
17020 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
17030 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
17040 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
17050 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
17060 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
17070 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
17080 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
17090 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
170a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
170b0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
170c0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
170d0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
170e0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
170f0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
17100 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
17110 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
17120 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
17130 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
17140 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
17150 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
17160 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
17170 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
17180 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
17190 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
171a0 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
171b0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
171c0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
171d0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
171e0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
171f0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
17200 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
17210 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
17220 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
17230 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
17240 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
17250 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
17260 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
17270 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
17280 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
17290 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
172a0 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
172b0 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
172c0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
172d0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
172e0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
172f0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
17300 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
17310 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
17320 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
17330 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
17340 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
17350 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
17360 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
17370 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
17380 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
17390 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
173a0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
173b0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
173c0 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
173d0 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
173e0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
173f0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
17400 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
17410 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
17420 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
17430 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
17440 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
17450 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
17460 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
17470 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
17480 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
17490 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
174a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
174b0 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
174c0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
174d0 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
174e0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
174f0 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
17500 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
17510 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
17520 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
17530 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
17540 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
17550 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
17560 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
17570 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
17580 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
17590 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
175a0 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
175b0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
175c0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
175d0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
175e0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
175f0 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
17600 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
17610 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
17620 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
17630 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
17640 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
17650 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
17660 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
17670 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
17680 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
17690 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
176a0 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
176b0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
176c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
176d0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
176e0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
176f0 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
17700 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
17710 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
17720 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
17730 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
17740 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
17750 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
17760 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
17770 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17780 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
17790 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
177a0 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
177b0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
177c0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
177d0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
177e0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
177f0 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
17800 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
17810 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
17820 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
17830 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
17840 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
17850 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
17860 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
17870 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
17880 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
17890 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
178a0 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
178b0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
178c0 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
178d0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
178e0 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
178f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17900 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
17910 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
17920 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
17930 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
17940 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
17950 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
17960 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
17970 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
17980 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
17990 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
179a0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
179b0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
179c0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
179d0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
179e0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
179f0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
17a00 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
17a10 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
17a20 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
17a30 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
17a40 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
17a50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
17a60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
17a70 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
17a80 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
17a90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17aa0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
17ab0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
17ac0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
17ad0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
17ae0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17af0 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
17b00 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
17b10 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
17b20 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
17b30 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
17b40 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
17b50 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
17b60 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
17b70 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
17b80 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
17b90 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
17ba0 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
17bb0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
17bc0 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
17bd0 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
17be0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
17bf0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
17c00 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
17c10 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
17c20 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
17c30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
17c40 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
17c50 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
17c60 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
17c70 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
17c80 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
17c90 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
17ca0 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
17cb0 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
17cc0 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
17cd0 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
17ce0 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
17cf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17d00 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
17d10 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
17d20 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
17d30 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nge..*/.int sqli
17d40 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17d50 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
17d60 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
17d70 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
17d80 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17d90 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
17da0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
17db0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
17dc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17dd0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
17de0 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
17df0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
17e00 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
17e10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17e20 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
17e30 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
17e40 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
17e50 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
17e60 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
17e70 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
17e80 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
17e90 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
17ea0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
17eb0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
17ec0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
17ed0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
17ee0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
17ef0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
17f00 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
17f10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17f20 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
17f30 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
17f40 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
17f50 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
17f60 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
17f70 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
17f80 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
17f90 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
17fa0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
17fb0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
17fc0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
17fd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
17fe0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
17ff0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
18000 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
18010 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
18020 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
18030 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
18040 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
18050 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
18060 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
18070 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
18080 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
18090 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
180a0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
180b0 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
180c0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
180d0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
180e0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
180f0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
18100 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18110 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
18120 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
18130 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
18140 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
18150 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
18160 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
18170 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
18180 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
18190 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
181a0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
181b0 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
181c0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
181d0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
181e0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
181f0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
18200 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
18210 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
18220 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
18230 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
18240 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
18250 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
18260 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
18270 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
18280 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
18290 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
182a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
182b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
182c0 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
182d0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
182e0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
182f0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
18300 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
18310 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
18320 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
18330 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
18340 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
18350 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
18360 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
18370 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18380 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18390 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
183a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
183b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
183c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
183d0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
183e0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
183f0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
18400 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
18410 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18420 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
18430 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
18440 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18450 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18460 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
18470 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
18480 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
18490 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
184a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
184b0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
184c0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
184d0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
184e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
184f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18500 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
18510 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
18520 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
18530 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
18540 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18550 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
18560 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
18570 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
18580 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18590 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
185a0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
185b0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
185c0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
185d0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
185e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
185f0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
18600 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
18610 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
18620 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18630 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18640 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
18650 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
18660 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18670 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18680 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18690 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
186a0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
186b0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
186c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
186d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
186e0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
186f0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
18700 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18710 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18720 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18730 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
18740 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
18750 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
18760 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
18770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18780 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
18790 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
187a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
187b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
187c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
187d0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
187e0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
187f0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
18800 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
18810 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
18820 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
18830 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
18840 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
18850 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
18860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
18870 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
18880 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
18890 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
188a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
188b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
188c0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
188d0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
188e0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
188f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18900 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
18910 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
18920 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
18930 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
18940 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
18950 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
18960 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
18970 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
18980 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
18990 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
189a0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
189b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
189c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
189d0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
189e0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
189f0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
18a00 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
18a10 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
18a20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18a30 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18a40 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
18a50 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
18a60 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
18a70 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
18a80 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18a90 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
18aa0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
18ab0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
18ac0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
18ad0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18ae0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
18af0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
18b00 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
18b10 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18b20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18b30 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
18b40 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
18b50 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
18b60 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
18b70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18b80 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
18b90 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
18ba0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
18bb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18bc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18bd0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
18be0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
18bf0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
18c00 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18c10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18c20 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
18c30 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
18c40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
18c50 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
18c60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18c70 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
18c80 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
18c90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
18ca0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
18cb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18cc0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
18cd0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
18ce0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
18cf0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
18d00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
18d10 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
18d20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
18d30 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
18d40 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
18d50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
18d60 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
18d70 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
18d80 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
18d90 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
18da0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
18db0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
18dc0 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
18dd0 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
18de0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
18df0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
18e00 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
18e10 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
18e20 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
18e30 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
18e40 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
18e50 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
18e60 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
18e70 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
18e80 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
18e90 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
18ea0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
18eb0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
18ec0 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
18ed0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
18ee0 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
18ef0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
18f00 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
18f10 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
18f20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
18f30 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
18f40 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
18f50 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
18f60 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
18f70 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
18f80 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
18f90 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
18fa0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
18fb0 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
18fc0 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
18fd0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
18fe0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
18ff0 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
19000 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
19010 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
19020 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
19030 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
19040 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
19050 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
19060 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )^.**.** ^The ca
19070 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
19080 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
19090 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
190a0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
190b0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
190c0 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
190d0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
190e0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
190f0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
19100 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
19110 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
19120 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
19130 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
19140 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
19150 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2f 0a 76 6f  ok to run..*/.vo
19160 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63  id *sqlite3_trac
19170 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  e(sqlite3*, void
19180 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c  (*xTrace)(void*,
19190 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f  const char*), vo
191a0 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50  id*);.SQLITE_EXP
191b0 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
191c0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
191d0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
191e0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
191f0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
19200 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
19210 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
19220 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
19230 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
19240 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
19250 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65 73  utine configures
19260 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
19270 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70 72  tion - the.** pr
19280 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
19290 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  - that is invoke
192a0 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
192b0 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72 75  uring long.** ru
192c0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20 5b  nning calls to [
192d0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
192e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
192f0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
19300 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e 20  3_get_table()]. 
19310 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
19320 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
19330 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
19340 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
19350 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
19360 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ery..**.** ^If t
19370 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
19380 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
19390 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
193a0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
193b0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
193c0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
193d0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
193e0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
193f0 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
19400 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
19410 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
19420 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75 73  ress handler mus
19430 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
19440 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
19450 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
19460 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
19470 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
19480 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
19490 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
194a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
194b0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
194c0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
194d0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
194e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
194f0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
19500 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
19510 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
19520 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
19530 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
19540 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
19550 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
19560 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
19570 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
19580 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
19590 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
195a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
195b0 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
195c0 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
195d0 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73  le whose name is
195e0 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a   given by the.**
195f0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
19600 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
19610 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
19620 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
19630 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
19640 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
19650 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
19660 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
19670 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
19680 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
19690 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
196a0 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
196b0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
196c0 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
196d0 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
196e0 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
196f0 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
19700 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
19710 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
19720 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
19730 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
19740 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
19750 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
19760 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
19770 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
19780 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
19790 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
197a0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
197b0 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
197c0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
197d0 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
197e0 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
197f0 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
19800 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
19810 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
19820 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
19830 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
19840 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
19850 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
19860 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
19870 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
19880 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
19890 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
198a0 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
198b0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
198c0 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
198d0 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
198e0 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
198f0 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
19900 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
19910 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
19920 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
19930 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
19940 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
19950 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19960 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
19970 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
19980 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
19990 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
199a0 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
199b0 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
199c0 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
199d0 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
199e0 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
199f0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
19a00 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
19a10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
19a20 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
19a30 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
19a40 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
19a50 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
19a60 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
19a70 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
19a80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
19a90 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
19aa0 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
19ab0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
19ac0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
19ad0 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
19ae0 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
19af0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
19b00 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
19b10 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
19b20 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
19b30 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
19b40 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
19b50 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
19b60 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
19b70 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
19b80 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
19b90 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
19ba0 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
19bb0 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
19bc0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
19bd0 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
19be0 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
19bf0 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ACHE],.** and/or
19c00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
19c10 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
19c20 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
19c30 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
19c40 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
19c50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
19c60 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
19c70 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
19c80 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
19c90 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
19ca0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
19cb0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
19cc0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
19cd0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
19ce0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
19cf0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
19d00 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
19d10 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
19d20 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
19d30 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
19d40 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
19d50 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
19d60 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
19d70 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
19d80 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
19d90 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
19da0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
19db0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
19dc0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
19dd0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
19de0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
19df0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
19e00 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
19e10 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
19e20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
19e30 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
19e40 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
19e50 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
19e60 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20  reates it if.** 
19e70 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
19e80 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
19e90 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
19ea0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
19eb0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
19ec0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
19ed0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
19ee0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
19ef0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
19f00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
19f10 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
19f20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
19f30 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
19f40 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72  s shown above or
19f50 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62   one of the comb
19f60 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
19f70 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a  bove combined.**
19f80 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
19f90 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
19fa0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
19fb0 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51  LLMUTEX],.** [SQ
19fc0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
19fd0 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53  CACHE] and/or [S
19fe0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
19ff0 44 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a  DCACHE] flags,.*
1a000 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
1a010 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
1a020 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1a030 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
1a040 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1a050 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
1a060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1a070 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
1a080 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
1a090 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
1a0a0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
1a0b0 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
1a0c0 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
1a0d0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1a0e0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
1a0f0 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
1a100 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1a110 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1a120 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
1a130 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a140 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
1a150 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
1a160 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
1a170 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
1a180 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
1a190 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
1a1a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
1a1b0 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
1a1c0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1a1d0 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
1a1e0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1a1f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a200 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
1a210 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
1a220 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
1a230 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1a240 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1a250 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
1a260 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
1a270 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
1a280 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
1a290 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
1a2a0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1a2b0 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
1a2c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a2d0 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
1a2e0 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
1a2f0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
1a300 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
1a310 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1a320 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
1a330 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1a340 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1a350 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
1a360 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
1a370 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1a380 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
1a390 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
1a3a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
1a3b0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
1a3c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a3d0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
1a3e0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1a3f0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1a400 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
1a410 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
1a420 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
1a430 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
1a440 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
1a450 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
1a460 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
1a470 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
1a480 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
1a490 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
1a4a0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
1a4b0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
1a4c0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
1a4d0 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
1a4e0 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
1a4f0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
1a500 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1a510 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
1a520 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
1a530 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1a540 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
1a550 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
1a560 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
1a570 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
1a580 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
1a590 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
1a5a0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
1a5b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1a5c0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1a5d0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
1a5e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
1a5f0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
1a600 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20  2() is the name 
1a610 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
1a620 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74  e3_vfs] object t
1a630 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
1a640 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
1a650 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a   interface that.
1a660 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  ** the new datab
1a670 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
1a680 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20  hould use.  ^If 
1a690 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
1a6a0 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c  eter is.** a NUL
1a6b0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
1a6c0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1a6d0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1a6e0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  is used..**.** <
1a6f0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1a700 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1a710 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1a720 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1a730 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1a740 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1a750 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1a760 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1a770 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1a780 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1a790 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1a7a0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1a7b0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1a7c0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1a7d0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1a7e0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1a7f0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1a800 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1a810 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1a820 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1a830 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
1a840 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
1a850 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1a860 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1a870 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1a880 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1a890 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1a8a0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1a8b0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1a8c0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
1a8d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
1a8e0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1a8f0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1a900 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
1a910 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1a920 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1a930 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1a940 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1a950 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1a960 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1a970 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1a980 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1a990 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1a9a0 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1a9b0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1a9c0 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1a9d0 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1a9e0 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1a9f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1aa00 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1aa10 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1aa20 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1aa30 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1aa40 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1aa50 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
1aa60 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1aa70 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1aa80 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
1aa90 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1aaa0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1aab0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1aac0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
1aad0 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
1aae0 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
1aaf0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
1ab00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ab10 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
1ab20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
1ab30 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
1ab40 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1ab50 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1ab60 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1ab70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
1ab80 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
1ab90 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1aba0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1abb0 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
1abc0 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
1abd0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
1abe0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1abf0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1ac00 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
1ac10 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
1ac20 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
1ac30 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
1ac40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1ac50 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1ac60 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1ac70 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1ac80 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1ac90 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1aca0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1acb0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1acc0 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1acd0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
1ace0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1acf0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1ad00 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1ad10 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1ad20 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1ad30 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1ad40 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1ad50 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1ad60 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1ad70 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1ad80 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1ad90 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1ada0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1adb0 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1adc0 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1add0 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68  ions.)^.**.** Wh
1ade0 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
1adf0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1ae00 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
1ae10 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
1ae20 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
1ae30 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
1ae40 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
1ae50 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
1ae60 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
1ae70 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
1ae80 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
1ae90 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
1aea0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
1aeb0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
1aec0 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
1aed0 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
1aee0 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
1aef0 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
1af00 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1af10 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
1af20 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
1af30 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
1af40 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
1af50 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1af60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1af70 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
1af80 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
1af90 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
1afa0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
1afb0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
1afc0 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
1afd0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1afe0 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
1aff0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1b000 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
1b010 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
1b020 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
1b030 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
1b040 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
1b050 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
1b060 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
1b070 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
1b080 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
1b090 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
1b0a0 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
1b0b0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
1b0c0 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
1b0d0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
1b0e0 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
1b0f0 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
1b100 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1b110 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1b120 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
1b130 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1b140 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1b150 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1b160 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
1b170 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
1b180 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
1b190 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
1b1a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1b1b0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
1b1c0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
1b1d0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1b1e0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
1b1f0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
1b200 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
1b210 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
1b220 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
1b230 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
1b240 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
1b250 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
1b260 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
1b270 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
1b280 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
1b290 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
1b2a0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
1b2b0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
1b2c0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
1b2d0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
1b2e0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
1b2f0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
1b300 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
1b310 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
1b320 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1b330 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
1b340 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
1b350 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
1b360 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
1b370 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
1b380 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
1b390 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
1b3a0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
1b3b0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
1b3c0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
1b3d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1b3e0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
1b3f0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
1b400 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
1b410 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
1b420 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
1b430 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
1b440 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
1b450 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
1b460 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
1b470 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
1b480 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1b490 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
1b4a0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
1b4b0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
1b4c0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
1b4d0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
1b4e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1b4f0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
1b500 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
1b510 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
1b520 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
1b530 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
1b540 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
1b550 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
1b560 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
1b570 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
1b580 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
1b590 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
1b5a0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
1b5b0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
1b5c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1b5d0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
1b5e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b5f0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
1b600 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
1b610 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
1b620 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1b630 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
1b640 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1b650 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
1b660 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
1b670 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
1b680 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
1b690 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
1b6a0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
1b6b0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
1b6c0 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75 6e  struct.  The fun
1b6d0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1b6e0 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a 2a  e old limit.)^.*
1b6f0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
1b700 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
1b710 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
1b720 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
1b730 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74 68  ged..** ^(For th
1b740 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  e limit category
1b750 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54   of SQLITE_LIMIT
1b760 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61 20  _XYZ there is a 
1b770 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
1b780 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
1b790 2a 2a 20 73 65 74 20 62 79 20 61 20 63 6f 6d 70  ** set by a comp
1b7a0 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70 72  ile-time C prepr
1b7b0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e 61  ocessor macro na
1b7c0 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  med .** [limits 
1b7d0 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59 5a  | SQLITE_MAX_XYZ
1b7e0 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
1b7f0 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
1b800 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
1b810 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
1b820 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
1b830 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
1b840 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
1b850 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
1b860 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
1b870 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
1b880 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
1b890 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20  Run-time limits 
1b8a0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
1b8b0 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74   use in applicat
1b8c0 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65  ions that manage
1b8d0 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f  .** both their o
1b8e0 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  wn internal data
1b8f0 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61  base and also da
1b900 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65  tabases that are
1b910 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62   controlled.** b
1b920 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65  y untrusted exte
1b930 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41  rnal sources.  A
1b940 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63  n example applic
1b950 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61  ation might be a
1b960 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20  .** web browser 
1b970 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e  that has its own
1b980 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73   databases for s
1b990 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61  toring history a
1b9a0 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64  nd.** separate d
1b9b0 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c  atabases control
1b9c0 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70  led by JavaScrip
1b9d0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64  t applications d
1b9e0 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66  ownloaded.** off
1b9f0 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20   the Internet.  
1ba00 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  The internal dat
1ba10 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69  abases can be gi
1ba20 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65  ven the.** large
1ba30 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73  , default limits
1ba40 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e  .  Databases man
1ba50 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c  aged by external
1ba60 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20   sources can.** 
1ba70 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d  be given much sm
1ba80 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73  aller limits des
1ba90 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74  igned to prevent
1baa0 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72   a denial of ser
1bab0 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20  vice.** attack. 
1bac0 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68   Developers migh
1bad0 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75  t also want to u
1bae0 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
1baf0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
1bb00 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74  ].** interface t
1bb10 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f  o further contro
1bb20 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e  l untrusted SQL.
1bb30 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
1bb40 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72  e database.** cr
1bb50 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72  eated by an untr
1bb60 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e  usted script can
1bb70 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73   be contained us
1bb80 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f  ing the.** [max_
1bb90 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
1bba0 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  GMA]..**.** New 
1bbb0 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63  run-time limit c
1bbc0 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65  ategories may be
1bbd0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
1bbe0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e   releases..*/.in
1bbf0 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
1bc00 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
1bc10 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
1bc20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1bc30 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
1bc40 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
1bc50 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
1bc60 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
1bc70 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
1bc80 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
1bc90 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
1bca0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
1bcb0 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
1bcc0 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
1bcd0 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
1bce0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
1bcf0 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
1bd00 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
1bd10 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
1bd20 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
1bd30 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
1bd40 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
1bd50 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
1bd60 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
1bd70 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
1bd80 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
1bd90 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
1bda0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1bdb0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
1bdc0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
1bdd0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
1bde0 20 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a   row.<dd>)^.**.*
1bdf0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1be00 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
1be10 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1be20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1be30 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
1be40 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
1be50 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1be60 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1be70 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
1be80 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1be90 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1bea0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
1beb0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
1bec0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
1bed0 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
1bee0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1bef0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1bf00 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
1bf10 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
1bf20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
1bf30 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1bf40 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1bf50 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
1bf60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1bf70 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
1bf80 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
1bf90 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
1bfa0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1bfb0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
1bfc0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
1bfd0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1bfe0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1bff0 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
1c000 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
1c010 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
1c020 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1c030 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
1c040 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c050 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1c060 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
1c070 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
1c080 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
1c090 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1c0a0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1c0b0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1c0c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1c0d0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
1c0e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1c0f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1c100 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
1c110 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
1c120 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1c130 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
1c140 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
1c150 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1c160 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
1c170 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
1c180 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
1c190 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1c1a0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
1c1b0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
1c1c0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1c1d0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
1c1e0 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
1c1f0 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
1c200 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
1c210 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
1c220 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1c230 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1c240 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
1c250 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1c260 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65 73  ber of variables
1c270 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1c280 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a 2a  ment that can.**
1c290 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e 29   be bound.</dd>)
1c2a0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1c2b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
1c2c0 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
1c2d0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1c2e0 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
1c2f0 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
1c300 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
1c310 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
1c320 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
1c330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1c340 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
1c350 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
1c360 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
1c370 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
1c380 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
1c390 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
1c3a0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
1c3b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
1c3c0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1c3d0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
1c3e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
1c3f0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
1c400 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
1c410 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
1c420 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
1c430 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
1c440 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c450 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
1c460 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
1c470 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c480 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
1c490 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
1c4a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c4b0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
1c4c0 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
1c4d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c4e0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
1c4f0 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
1c500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c510 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
1c520 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
1c530 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c540 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
1c550 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
1c560 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
1c570 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
1c580 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
1c590 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
1c5a0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
1c5b0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
1c5c0 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
1c5d0 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
1c5e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1c5f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
1c600 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
1c610 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
1c620 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
1c630 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
1c640 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
1c650 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
1c660 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
1c670 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
1c680 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1c690 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
1c6a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c6b0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
1c6c0 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
1c6d0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
1c6e0 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
1c6f0 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
1c700 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
1c710 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
1c720 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
1c730 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
1c740 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1c750 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1c760 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
1c770 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
1c780 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
1c790 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
1c7a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1c7b0 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
1c7c0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
1c7d0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
1c7e0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
1c7f0 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
1c800 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
1c810 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
1c820 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
1c830 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1c840 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
1c850 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
1c860 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
1c870 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
1c880 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
1c890 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
1c8a0 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
1c8b0 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
1c8c0 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
1c8d0 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
1c8e0 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
1c8f0 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
1c900 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
1c910 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
1c920 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
1c930 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
1c940 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
1c950 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
1c960 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
1c970 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
1c980 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
1c990 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
1c9a0 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
1c9b0 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
1c9c0 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
1c9d0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
1c9e0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
1c9f0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
1ca00 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
1ca10 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a  inator bytes..**
1ca20 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
1ca30 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
1ca40 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
1ca50 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
1ca60 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
1ca70 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
1ca80 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
1ca90 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
1caa0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1cab0 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
1cac0 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
1cad0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
1cae0 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
1caf0 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
1cb00 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
1cb10 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
1cb20 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
1cb30 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
1cb40 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
1cb50 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
1cb60 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
1cb70 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1cb80 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
1cb90 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
1cba0 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
1cbb0 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
1cbc0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
1cbd0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
1cbe0 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
1cbf0 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
1cc00 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
1cc10 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
1cc20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
1cc30 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
1cc40 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
1cc50 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
1cc60 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
1cc70 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
1cc80 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
1cc90 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
1cca0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
1ccb0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
1ccc0 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
1ccd0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
1cce0 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
1ccf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1cd00 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
1cd10 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
1cd20 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
1cd30 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
1cd40 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
1cd50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1cd60 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1cd70 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1cd80 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
1cd90 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
1cda0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
1cdb0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
1cdc0 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
1cdd0 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
1cde0 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
1cdf0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1ce00 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
1ce10 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
1ce20 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
1ce30 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
1ce40 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
1ce50 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
1ce60 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
1ce70 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
1ce80 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
1ce90 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
1cea0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
1ceb0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
1cec0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1ced0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
1cee0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
1cef0 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
1cf00 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
1cf10 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
1cf20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
1cf30 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
1cf40 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
1cf50 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
1cf60 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
1cf70 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
1cf80 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1cf90 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
1cfa0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
1cfb0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
1cfc0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
1cfd0 20 69 74 20 61 67 61 69 6e 2e 20 20 5e 49 66 20   it again.  ^If 
1cfe0 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20 63  the schema has c
1cff0 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20 77  hanged in.** a w
1d000 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  ay that makes th
1d010 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20 6c  e statement no l
1d020 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73 71  onger valid, [sq
1d030 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
1d040 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74 75  ll still.** retu
1d050 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  rn [SQLITE_SCHEM
1d060 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65 20  A].  But unlike 
1d070 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
1d080 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  ior, [SQLITE_SCH
1d090 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20 61  EMA] is.** now a
1d0a0 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20 43   fatal error.  C
1d0b0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1d0c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 67  prepare_v2()] ag
1d0d0 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61 6b  ain will not mak
1d0e0 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 67  e the.** error g
1d0f0 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20 75  o away.  Note: u
1d100 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  se [sqlite3_errm
1d110 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74 68  sg()] to find th
1d120 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68 65  e text.** of the
1d130 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20 74   parsing error t
1d140 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20 61  hat results in a
1d150 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  n [SQLITE_SCHEMA
1d160 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f 6c  ] return..** </l
1d170 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1d180 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
1d190 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
1d1a0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
1d1b0 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
1d1c0 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
1d1d0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
1d1e0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
1d1f0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
1d200 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
1d210 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
1d220 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
1d230 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
1d240 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
1d250 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
1d260 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
1d270 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
1d280 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
1d290 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
1d2a0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
1d2b0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
1d2c0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
1d2d0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
1d2e0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
1d2f0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
1d300 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
1d310 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
1d320 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
1d330 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1d340 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1d350 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
1d360 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 61  f the value of a
1d370 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
1d380 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
1d390 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75 73   the WHERE claus
1d3a0 65 20 6d 69 67 68 74 0a 2a 2a 20 63 68 61 6e 67  e might.** chang
1d3b0 65 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e  e the query plan
1d3c0 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
1d3d0 2c 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  , then the state
1d3e0 6d 65 6e 74 20 6d 61 79 20 62 65 0a 2a 2a 20 61  ment may be.** a
1d3f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
1d400 6f 6d 70 69 6c 65 64 20 28 61 73 20 69 66 20 74  ompiled (as if t
1d410 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 61 20  here had been a 
1d420 73 63 68 65 6d 61 20 63 68 61 6e 67 65 29 20 6f  schema change) o
1d430 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a 2a 20  n the first .** 
1d440 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1d450 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
1d460 61 6e 79 20 63 68 61 6e 67 65 20 74 6f 20 74 68  any change to th
1d470 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  e .** [sqlite3_b
1d480 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
1d490 6e 67 73 5d 20 6f 66 20 74 68 65 20 5b 70 61 72  ngs] of the [par
1d4a0 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f 6c  ameter]. .** </l
1d4b0 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
1d4c0 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1d4d0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
1d4e0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
1d4f0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
1d500 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1d510 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
1d520 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
1d530 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
1d540 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1d550 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1d560 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1d570 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1d580 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1d590 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1d5a0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1d5b0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1d5c0 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
1d5d0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1d5e0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1d5f0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1d600 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1d610 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
1d620 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1d630 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1d640 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1d650 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1d660 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1d670 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1d680 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1d690 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1d6a0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1d6b0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1d6c0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1d6d0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1d6e0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1d6f0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1d700 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1d710 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1d720 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1d730 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1d740 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1d750 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
1d760 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1d770 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1d780 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1d790 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
1d7a0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1d7b0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
1d7c0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
1d7d0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1d7e0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1d7f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1d800 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1d810 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1d820 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1d830 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1d840 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1d850 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1d860 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1d870 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1d880 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1d890 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1d8a0 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
1d8b0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1d8c0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1d8d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1d8e0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
1d8f0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1d900 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
1d910 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
1d920 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
1d930 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
1d940 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
1d950 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
1d960 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
1d970 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
1d980 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
1d990 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
1d9a0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
1d9b0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
1d9c0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
1d9d0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1d9e0 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
1d9f0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
1da00 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
1da10 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
1da20 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
1da30 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
1da40 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
1da50 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
1da60 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
1da70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
1da80 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
1da90 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
1daa0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
1dab0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1dac0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1dad0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1dae0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
1daf0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
1db00 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
1db10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1db20 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
1db30 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
1db40 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
1db50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1db60 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
1db70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
1db80 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
1db90 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
1dba0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
1dbb0 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
1dbc0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
1dbd0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
1dbe0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1dbf0 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
1dc00 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
1dc10 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
1dc20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
1dc30 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
1dc40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1dc50 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
1dc60 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
1dc70 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
1dc80 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
1dc90 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
1dca0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
1dcb0 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
1dcc0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
1dcd0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
1dce0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
1dcf0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
1dd00 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1dd10 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
1dd20 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
1dd30 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
1dd40 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
1dd50 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
1dd60 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
1dd70 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
1dd80 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
1dd90 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
1dda0 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
1ddb0 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
1ddc0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
1ddd0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1dde0 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
1ddf0 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
1de00 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
1de10 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
1de20 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
1de30 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
1de40 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75  .  A internal mu
1de50 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
1de60 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
1de70 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1de80 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
1de90 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
1dea0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
1deb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1dec0 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
1ded0 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
1dee0 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
1def0 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
1df00 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
1df10 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
1df20 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
1df30 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
1df40 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
1df50 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
1df60 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
1df70 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
1df80 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
1df90 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
1dfa0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
1dfb0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
1dfc0 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
1dfd0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
1dfe0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
1dff0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
1e000 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
1e010 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
1e020 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
1e030 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
1e040 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
1e050 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
1e060 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
1e070 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
1e080 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
1e090 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
1e0a0 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e 20  between between 
1e0b0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
1e0c0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
1e0d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e0e0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
1e0f0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
1e100 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1e110 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1e120 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
1e130 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
1e140 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
1e150 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1e160 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
1e170 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1e180 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
1e190 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
1e1a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1e1b0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
1e1c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1e1d0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
1e1e0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
1e1f0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1e200 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
1e210 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
1e220 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
1e230 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
1e240 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
1e250 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
1e260 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
1e270 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
1e280 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
1e290 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
1e2a0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
1e2b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e2c0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
1e2d0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
1e2e0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
1e2f0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
1e300 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
1e310 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
1e320 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
1e330 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
1e340 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
1e350 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
1e360 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
1e370 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
1e380 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
1e390 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
1e3a0 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
1e3b0 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
1e3c0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
1e3d0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
1e3e0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
1e3f0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1e400 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
1e410 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
1e420 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
1e430 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
1e440 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
1e450 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
1e460 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
1e470 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
1e480 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
1e490 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
1e4a0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
1e4b0 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
1e4c0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
1e4d0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
1e4e0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
1e4f0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
1e500 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
1e510 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
1e520 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
1e530 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
1e540 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
1e550 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
1e560 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
1e570 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
1e580 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
1e590 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
1e5a0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
1e5b0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
1e5c0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
1e5d0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
1e5e0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
1e5f0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
1e600 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28  inding}.**.** ^(
1e610 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  In the SQL state
1e620 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20  ment text input 
1e630 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  to [sqlite3_prep
1e640 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74  are_v2()] and it
1e650 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c  s variants,.** l
1e660 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72  iterals may be r
1e670 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61  eplaced by a [pa
1e680 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61  rameter] that ma
1e690 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c  tches one of fol
1e6a0 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61  lowing.** templa
1e6b0 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  tes:.**.** <ul>.
1e6c0 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c  ** <li>  ?.** <l
1e6d0 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e  i>  ?NNN.** <li>
1e6e0 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    :VVV.** <li>  
1e6f0 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56  @VVV.** <li>  $V
1e700 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VV.** </ul>.**.*
1e710 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74  * In the templat
1e720 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65  es above, NNN re
1e730 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65  presents an inte
1e740 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20  ger literal,.** 
1e750 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e  and VVV represen
1e760 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72  ts an alphanumer
1e770 69 63 20 69 64 65 6e 74 69 66 65 72 2e 29 5e 20  ic identifer.)^ 
1e780 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
1e790 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
1e7a0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
1e7b0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
1e7c0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
1e7d0 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
1e7e0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
1e7f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1e800 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
1e810 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
1e820 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1e830 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
1e840 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1e850 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
1e860 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
1e870 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
1e880 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
1e890 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
1e8a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e8b0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1e8c0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1e8d0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
1e8e0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
1e8f0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
1e900 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
1e910 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
1e920 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
1e930 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
1e940 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
1e950 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
1e960 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
1e970 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
1e980 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
1e990 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
1e9a0 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
1e9b0 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
1e9c0 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
1e9d0 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
1e9e0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
1e9f0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
1ea00 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
1ea10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
1ea20 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
1ea30 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
1ea40 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
1ea50 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
1ea60 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
1ea70 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
1ea80 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
1ea90 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
1eaa0 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
1eab0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
1eac0 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
1ead0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
1eae0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
1eaf0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
1eb00 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
1eb10 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
1eb20 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
1eb30 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
1eb40 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
1eb50 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
1eb60 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
1eb70 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
1eb80 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
1eb90 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
1eba0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
1ebb0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
1ebc0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
1ebd0 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
1ebe0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
1ebf0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
1ec00 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
1ec10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
1ec20 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
1ec30 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65  negative, the le
1ec40 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
1ec50 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
1ec60 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
1ec70 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
1ec80 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
1ec90 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
1eca0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1ecb0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
1ecc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
1ecd0 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
1ece0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
1ecf0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
1ed00 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
1ed10 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
1ed20 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
1ed30 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
1ed40 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 5e 49  shed with it. ^I
1ed50 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
1ed60 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
1ed70 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
1ed80 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
1ed90 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
1eda0 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
1edb0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
1edc0 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
1edd0 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
1ede0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
1edf0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
1ee00 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
1ee10 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
1ee20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
1ee30 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
1ee40 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
1ee50 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
1ee60 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
1ee70 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
1ee80 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
1ee90 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
1eea0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
1eeb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
1eec0 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
1eed0 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
1eee0 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
1eef0 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
1ef00 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
1ef10 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
1ef20 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
1ef30 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
1ef40 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
1ef50 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
1ef60 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
1ef70 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
1ef80 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
1ef90 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
1efa0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
1efb0 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
1efc0 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
1efd0 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
1efe0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
1eff0 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
1f000 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
1f010 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
1f020 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
1f030 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
1f040 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
1f050 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
1f060 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
1f070 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
1f080 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
1f090 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1f0a0 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
1f0b0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
1f0c0 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
1f0d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
1f0e0 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
1f0f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f100 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
1f110 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
1f120 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
1f130 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
1f140 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
1f150 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
1f160 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
1f170 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
1f180 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
1f190 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
1f1a0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
1f1b0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
1f1c0 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
1f1d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
1f1e0 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
1f1f0 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
1f200 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
1f210 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
1f220 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
1f230 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
1f240 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
1f250 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1f260 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
1f270 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
1f280 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1f290 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
1f2a0 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
1f2b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
1f2c0 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
1f2d0 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
1f2e0 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
1f2f0 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
1f300 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
1f310 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
1f320 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
1f330 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
1f340 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
1f350 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1f360 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1f370 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
1f380 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
1f390 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
1f3a0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1f3b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1f3c0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
1f3d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
1f3e0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
1f3f0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
1f400 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
1f410 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
1f420 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
1f430 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
1f440 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
1f450 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1f460 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
1f470 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
1f480 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1f490 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
1f4a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
1f4b0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
1f4c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
1f4d0 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
1f4e0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
1f4f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
1f500 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1f510 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
1f520 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
1f530 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
1f540 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
1f550 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1f560 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
1f570 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
1f580 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
1f590 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
1f5a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
1f5b0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
1f5c0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
1f5d0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
1f5e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1f5f0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
1f600 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
1f610 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
1f620 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
1f630 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
1f640 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
1f650 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
1f660 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
1f670 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
1f680 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
1f690 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
1f6a0 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
1f6b0 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
1f6c0 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
1f6d0 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
1f6e0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
1f6f0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
1f700 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
1f710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f720 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
1f730 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
1f740 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
1f750 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
1f760 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
1f770 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
1f780 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
1f790 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
1f7a0 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
1f7b0 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
1f7c0 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
1f7d0 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
1f7e0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
1f7f0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
1f800 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
1f810 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
1f820 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
1f830 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
1f840 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
1f850 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
1f860 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
1f870 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
1f880 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
1f890 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
1f8a0 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
1f8b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1f8c0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
1f8d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
1f8e0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
1f8f0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
1f900 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1f910 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
1f920 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
1f930 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f940 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1f950 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
1f960 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
1f970 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
1f980 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
1f990 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
1f9a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1f9b0 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
1f9c0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
1f9d0 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
1f9e0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
1f9f0 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
1fa00 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
1fa10 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
1fa20 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
1fa30 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
1fa40 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
1fa50 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
1fa60 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
1fa70 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
1fa80 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
1fa90 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
1faa0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
1fab0 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
1fac0 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
1fad0 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
1fae0 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
1faf0 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
1fb00 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
1fb10 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
1fb20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
1fb30 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
1fb40 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
1fb50 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
1fb60 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
1fb70 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
1fb80 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
1fb90 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
1fba0 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
1fbb0 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
1fbc0 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
1fbd0 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
1fbe0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
1fbf0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
1fc00 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
1fc10 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
1fc20 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
1fc30 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
1fc40 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
1fc50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1fc60 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
1fc70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1fc80 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
1fc90 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
1fca0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
1fcb0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
1fcc0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1fcd0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
1fce0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1fcf0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
1fd00 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
1fd10 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1fd20 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1fd30 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
1fd40 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
1fd50 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
1fd60 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
1fd70 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
1fd80 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
1fd90 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
1fda0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
1fdb0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
1fdc0 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
1fdd0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
1fde0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
1fdf0 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
1fe00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
1fe10 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
1fe20 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
1fe30 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
1fe40 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
1fe50 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
1fe60 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
1fe70 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
1fe80 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
1fe90 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
1fea0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
1feb0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
1fec0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
1fed0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
1fee0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1fef0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
1ff00 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
1ff10 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
1ff20 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
1ff30 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1ff40 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
1ff50 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
1ff60 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
1ff70 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
1ff80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
1ff90 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
1ffa0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
1ffb0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
1ffc0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
1ffd0 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
1ffe0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
1fff0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
20000 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
20010 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
20020 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
20030 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
20040 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
20050 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
20060 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
20070 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
20080 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
20090 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
200a0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
200b0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
200c0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
200d0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
200e0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
200f0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
20100 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
20110 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
20120 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
20130 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
20140 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
20150 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
20160 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
20170 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20180 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
20190 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
201a0 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
201b0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
201c0 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
201d0 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
201e0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
201f0 5d 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ])..*/.int sqlit
20200 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
20210 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
20220 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
20230 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
20240 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
20250 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
20260 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
20270 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
20280 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
20290 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
202a0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
202b0 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
202c0 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
202d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
202e0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
202f0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
20300 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
20310 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
20320 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
20330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
20340 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
20350 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
20360 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
20370 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
20380 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
20390 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
203a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
203b0 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
203c0 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
203d0 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
203e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
203f0 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
20400 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
20410 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
20420 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
20430 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
20440 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
20450 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
20460 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
20470 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
20480 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
20490 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
204a0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
204b0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
204c0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
204d0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
204e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
204f0 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
20500 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
20510 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
20520 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
20530 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
20540 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
20550 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
20560 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
20570 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
20580 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
20590 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
205a0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
205b0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
205c0 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
205d0 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
205e0 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
205f0 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
20600 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
20610 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
20620 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
20630 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
20640 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
20650 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
20660 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
20670 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
20680 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
20690 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
206a0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
206b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
206c0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
206d0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
206e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
206f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
20700 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
20710 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
20720 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
20730 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
20740 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Result.**.** ^Th
20750 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
20760 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
20770 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
20780 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
20790 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
207a0 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
207b0 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
207c0 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
207d0 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
207e0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
207f0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
20800 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
20810 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
20820 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
20830 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
20840 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
20850 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
20860 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
20870 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
20880 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
20890 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
208a0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
208b0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
208c0 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
208d0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
208e0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
208f0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
20900 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
20910 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
20920 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
20930 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
20940 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
20950 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
20960 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
20970 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
20980 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
20990 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
209a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
209b0 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
209c0 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
209d0 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
209e0 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
209f0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
20a00 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
20a10 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
20a20 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
20a30 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
20a40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
20a50 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
20a60 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
20a70 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
20a80 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
20a90 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
20aa0 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
20ab0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
20ac0 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
20ad0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
20ae0 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
20af0 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
20b00 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
20b10 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
20b20 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
20b30 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
20b40 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
20b50 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
20b60 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
20b70 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
20b80 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
20b90 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
20ba0 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
20bb0 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
20bc0 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
20bd0 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
20be0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
20bf0 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
20c00 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
20c10 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
20c20 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
20c30 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
20c40 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
20c50 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
20c60 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
20c70 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
20c80 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
20c90 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
20ca0 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
20cb0 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
20cc0 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
20cd0 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
20ce0 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
20cf0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
20d00 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
20d10 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
20d20 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
20d30 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
20d40 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
20d50 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
20d60 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
20d70 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
20d80 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
20d90 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
20da0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
20db0 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
20dc0 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
20dd0 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
20de0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20df0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
20e00 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
20e10 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
20e20 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
20e30 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
20e40 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
20e50 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
20e60 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
20e70 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
20e80 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
20e90 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
20ea0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
20eb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20ec0 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
20ed0 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
20ee0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
20ef0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
20f00 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
20f10 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
20f20 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
20f30 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
20f40 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
20f50 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
20f60 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
20f70 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
20f80 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
20f90 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
20fa0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
20fb0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
20fc0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
20fd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
20fe0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
20ff0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
21000 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
21010 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
21020 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
21030 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
21040 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
21050 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
21060 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
21070 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
21080 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
21090 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
210a0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
210b0 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
210c0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
210d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
210e0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
210f0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
21100 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
21110 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
21120 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
21130 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
21140 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
21150 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
21160 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
21170 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
21180 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
21190 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
211a0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
211b0 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
211c0 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
211d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
211e0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
211f0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
21200 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
21210 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
21220 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
21230 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
21240 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
21250 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
21260 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
21270 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
21280 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
21290 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
212a0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
212b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
212c0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
212d0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
212e0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
212f0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
21300 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
21310 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
21320 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
21330 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
21340 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
21350 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
21360 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
21370 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
21380 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
21390 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
213a0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
213b0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
213c0 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
213d0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
213e0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
213f0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
21400 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
21410 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
21420 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
21430 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
21440 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
21450 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
21460 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
21470 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
21480 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
21490 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
214a0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
214b0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
214c0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
214d0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
214e0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
214f0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
21500 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
21510 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
21520 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
21530 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
21540 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
21550 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
21560 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
21570 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
21580 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
21590 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
215a0 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
215b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
215c0 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
215d0 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
215e0 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
215f0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
21600 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
21610 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
21620 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
21630 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
21640 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
21650 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
21660 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
21670 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
21680 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
21690 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
216a0 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
216b0 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
216c0 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
216d0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
216e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
216f0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
21700 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
21710 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
21720 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
21730 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
21740 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
21750 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21760 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
21770 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
21780 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
21790 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
217a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
217b0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
217c0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
217d0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
217e0 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
217f0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
21800 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
21810 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
21820 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
21830 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
21840 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
21850 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
21860 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
21870 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
21880 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
21890 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
218a0 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
218b0 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
218c0 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
218d0 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
218e0 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
218f0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
21900 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
21910 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
21920 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
21930 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
21940 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
21950 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
21960 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
21970 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
21980 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
21990 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
219a0 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
219b0 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
219c0 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
219d0 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
219e0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
219f0 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
21a00 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
21a10 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
21a20 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
21a30 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
21a40 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
21a50 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
21a60 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
21a70 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
21a80 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74  in a.** explicit
21a90 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
21aa0 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
21ab0 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
21ac0 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
21ad0 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
21ae0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
21af0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
21b00 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
21b10 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
21b20 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
21b30 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
21b40 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
21b50 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
21b60 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
21b70 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
21b80 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
21b90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
21ba0 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
21bb0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
21bc0 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
21bd0 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
21be0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
21bf0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
21c00 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
21c10 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
21c20 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
21c30 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
21c40 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
21c50 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
21c60 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
21c70 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
21c80 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
21c90 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
21ca0 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
21cb0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
21cc0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
21cd0 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
21ce0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
21cf0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
21d00 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
21d10 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
21d20 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
21d30 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
21d40 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
21d50 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
21d60 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
21d70 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
21d80 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
21d90 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
21da0 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
21db0 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
21dc0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
21dd0 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
21de0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
21df0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
21e00 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
21e10 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
21e20 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
21e30 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
21e40 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
21e50 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
21e60 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
21e70 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
21e80 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
21e90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
21ea0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
21eb0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
21ec0 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
21ed0 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
21ee0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
21ef0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
21f00 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
21f10 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
21f20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
21f30 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
21f40 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
21f50 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
21f60 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
21f70 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
21f80 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
21f90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
21fa0 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
21fb0 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
21fc0 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
21fd0 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
21fe0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
21ff0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
22000 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
22010 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
22020 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
22030 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
22040 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
22050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22060 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
22070 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
22080 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
22090 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
220a0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
220b0 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
220c0 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
220d0 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
220e0 31 2c 20 69 74 20 77 61 73 20 72 65 71 75 69 72  1, it was requir
220f0 65 64 0a 2a 2a 20 61 66 74 65 72 20 73 71 6c 69  ed.** after sqli
22100 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
22110 6e 65 64 20 61 6e 79 74 68 69 6e 67 20 6f 74 68  ned anything oth
22120 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
22130 52 4f 57 5d 20 74 68 61 74 0a 2a 2a 20 5b 73 71  ROW] that.** [sq
22140 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 62  lite3_reset()] b
22150 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
22160 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69  any subsequent i
22170 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
22180 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
22190 20 46 61 69 6c 75 72 65 20 74 6f 20 69 6e 76 6f   Failure to invo
221a0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ke [sqlite3_rese
221b0 74 28 29 5d 20 69 6e 20 74 68 69 73 20 77 61 79  t()] in this way
221c0 20 77 6f 75 6c 64 0a 2a 2a 20 72 65 73 75 6c 74   would.** result
221d0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
221e0 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
221f0 6f 6d 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  om sqlite3_step(
22200 29 2e 20 20 42 75 74 20 61 66 74 65 72 0a 2a 2a  ).  But after.**
22210 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
22220 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
22230 29 20 62 65 67 61 6e 20 63 61 6c 6c 69 6e 67 20  ) began calling 
22240 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22250 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ] .** automatica
22260 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63  lly in this circ
22270 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 20  umstance rather 
22280 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
22290 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
222a0 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79   .**.** <b>Goofy
222b0 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74   Interface Alert
222c0 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67  :</b> In the leg
222d0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
222e0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
222f0 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20  ).** API always 
22300 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69  returns a generi
22310 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53  c error code, [S
22320 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f  QLITE_ERROR], fo
22330 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65  llowing any.** e
22340 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20  rror other than 
22350 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e  [SQLITE_BUSY] an
22360 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  d [SQLITE_MISUSE
22370 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c  ].  You must cal
22380 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  l.** [sqlite3_re
22390 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
223a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
223b0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
223c0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70  one of the.** sp
223d0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
223e0 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72  des] that better
223f0 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
22400 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69  rror..** We admi
22410 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61  t that this is a
22420 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20   goofy design.  
22430 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20  The problem has 
22440 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69  been fixed.** wi
22450 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
22460 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70  rface.  If you p
22470 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f  repare all of yo
22480 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ur SQL statement
22490 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65  s.** using eithe
224a0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
224b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
224c0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
224d0 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20  2()] instead.** 
224e0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73  of the legacy [s
224f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
22500 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
22510 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65  repare16()] inte
22520 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20  rfaces,.** then 
22530 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
22540 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
22550 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72  are returned dir
22560 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69  ectly.** by sqli
22570 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65  te3_step().  The
22580 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22   use of the "v2"
22590 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
225a0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e  commended..*/.in
225b0 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73  t sqlite3_step(s
225c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
225d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
225e0 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  Number of column
225f0 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65  s in a result se
22600 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
22610 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
22620 50 29 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  P) the number of
22630 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
22640 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
22650 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65   set of [prepare
22660 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
22670 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
22680 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
22690 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
226a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
226b0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
226c0 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
226d0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
226e0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
226f0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
22700 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
22710 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
22720 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
22730 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
22740 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
22750 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
22760 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
22770 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
22780 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
22790 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
227a0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
227b0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
227c0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
227d0 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
227e0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
227f0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
22800 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
22810 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
22820 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
22830 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
22840 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
22850 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
22860 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
22870 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
22880 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
22890 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
228a0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
228b0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
228c0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
228d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
228e0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
228f0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
22900 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
22910 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
22920 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
22930 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
22940 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
22950 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
22960 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
22970 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
22980 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
22990 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
229a0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
229b0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
229c0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
229d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
229e0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
229f0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
22a00 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
22a10 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
22a20 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
22a30 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
22a40 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
22a50 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
22a60 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
22a70 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
22a80 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
22a90 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
22aa0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
22ab0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
22ac0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
22ad0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22ae0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
22af0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
22b00 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
22b10 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
22b20 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
22b30 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
22b40 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
22b50 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
22b60 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
22b70 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
22b80 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
22b90 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
22ba0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
22bb0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
22bc0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
22bd0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
22be0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
22bf0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
22c00 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
22c10 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
22c20 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
22c30 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
22c40 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
22c50 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
22c60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
22c70 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
22c80 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
22c90 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
22ca0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
22cb0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
22cc0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
22cd0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
22ce0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
22cf0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
22d00 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
22d10 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
22d20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
22d30 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
22d40 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
22d50 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
22d60 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
22d70 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
22d80 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
22d90 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
22da0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
22db0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
22dc0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
22dd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22de0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
22df0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
22e00 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
22e10 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
22e20 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
22e30 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
22e40 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
22e50 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
22e60 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
22e70 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
22e80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
22e90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
22ea0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
22eb0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
22ec0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
22ed0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
22ee0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
22ef0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
22f00 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
22f10 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
22f20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
22f30 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
22f40 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
22f50 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
22f60 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
22f70 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
22f80 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
22f90 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
22fa0 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
22fb0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
22fc0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
22fd0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
22fe0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
22ff0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
23000 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
23010 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
23020 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
23030 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
23040 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
23050 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
23060 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
23070 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
23080 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
23090 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
230a0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
230b0 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
230c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
230d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
230e0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
230f0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
23100 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
23110 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
23120 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
23130 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
23140 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
23150 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
23160 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
23170 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
23180 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
23190 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
231a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
231b0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
231c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
231d0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
231e0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
231f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
23200 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
23210 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
23220 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
23230 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
23240 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
23250 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
23260 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
23270 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
23280 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
23290 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
232a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
232b0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
232c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
232d0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
232e0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
232f0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
23300 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
23310 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
23320 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
23330 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74  * ^The value ret
23340 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
23350 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
23360 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74 68  terminator at th
23370 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
23380 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
23390 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
233a0 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68 65   returned is the
233b0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
233c0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
233d0 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
233e0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
233f0 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
23400 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
23410 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23420 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
23430 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
23440 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
23450 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
23460 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64   zero terminated
23470 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
23480 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
23490 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
234a0 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
234b0 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e 20  ngth BLOB is an 
234c0 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f 69  arbitrary.** poi
234d0 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20 65  nter, possibly e
234e0 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ven a NULL point
234f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
23500 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23510 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65 20  tes16() routine 
23520 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73 71  is similar to sq
23530 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
23540 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61 76  es().** but leav
23550 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  es the result in
23560 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
23570 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e 73  e byte order ins
23580 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a 2a  tead of UTF-8..*
23590 2a 20 5e 54 68 65 20 7a 65 72 6f 20 74 65 72 6d  * ^The zero term
235a0 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69 6e  inator is not in
235b0 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20 63  cluded in this c
235c0 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ount..**.** ^The
235d0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
235e0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
235f0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
23600 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
23610 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
23620 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
23630 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
23640 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
23650 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
23660 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
23670 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
23680 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
23690 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
236a0 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
236b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
236c0 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
236d0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
236e0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
236f0 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
23700 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
23710 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
23720 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
23730 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
23740 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
23750 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
23760 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
23770 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
23780 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
23790 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
237a0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
237b0 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
237c0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
237d0 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
237e0 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
237f0 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
23800 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
23810 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
23820 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
23830 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
23840 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
23850 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
23860 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
23870 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
23880 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
23890 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
238a0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
238b0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
238c0 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
238d0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
238e0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
238f0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
23900 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
23910 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
23920 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
23930 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
23940 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
23950 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
23960 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
23970 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
23980 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
23990 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
239a0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
239b0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
239c0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
239d0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
239e0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
239f0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
23a00 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
23a10 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
23a20 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
23a30 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
23a40 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
23a50 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
23a60 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
23a70 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
23a80 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
23a90 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
23aa0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
23ab0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
23ac0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
23ad0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
23ae0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
23af0 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
23b00 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
23b10 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
23b20 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
23b30 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
23b40 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
23b50 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
23b60 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
23b70 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
23b80 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
23b90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
23ba0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
23bb0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
23bc0 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
23bd0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
23be0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
23bf0 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
23c00 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
23c10 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
23c20 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
23c30 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
23c40 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
23c50 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
23c60 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
23c70 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
23c80 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
23c90 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
23ca0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
23cb0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
23cc0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
23cd0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
23ce0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
23cf0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
23d00 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
23d10 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
23d20 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
23d30 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
23d40 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
23d50 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
23d60 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
23d70 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
23d80 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
23d90 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
23da0 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
23db0 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
23dc0 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
23dd0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
23de0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
23df0 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
23e00 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
23e10 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
23e20 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
23e30 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
23e40 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
23e50 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
23e60 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
23e70 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
23e80 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
23e90 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  mers..**.** ^Not
23ea0 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
23eb0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
23ec0 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
23ed0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
23ee0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
23ef0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
23f00 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
23f10 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
23f20 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
23f30 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
23f40 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
23f50 2a 20 5e 28 54 79 70 65 20 63 6f 6e 76 65 72 73  * ^(Type convers
23f60 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
23f70 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
23f80 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
23f90 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
23fa0 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
23fb0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
23fc0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
23fd0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
23fe0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
23ff0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
24000 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
24010 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
24020 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
24030 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
24040 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
24050 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
24060 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
24070 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
24080 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
24090 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
240a0 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
240b0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
240c0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
240d0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
240e0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
240f0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
24100 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
24110 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
24120 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
24130 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
24140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
24150 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
24160 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
24170 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
24180 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
24190 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
241a0 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
241b0 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
241c0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  >)^.**.** ^Conve
241d0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
241e0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
241f0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
24200 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
24210 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
24220 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
24230 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
24240 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
24250 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
24260 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
24270 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f 69  rior pointer poi
24280 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76 65  nts to will have
24290 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
242a0 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
242b0 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
242c0 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
242d0 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
242e0 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
242f0 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
24300 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
24310 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
24320 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
24330 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
24340 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 61 66 65 73  *.** ^(The safes
24350 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f  t and easiest to
24360 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79   remember policy
24370 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68   is to invoke th
24380 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
24390 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  in one of the fo
243a0 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a  llowing ways:.**
243b0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69  .** <ul>.**  <li
243c0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
243d0 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20  text() followed 
243e0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
243f0 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
24400 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
24410 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c  olumn_blob() fol
24420 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
24430 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
24440 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
24450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24460 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  16() followed by
24470 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24480 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a  bytes16()</li>.*
24490 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
244a0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
244b0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
244c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
244d0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
244e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
244f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
24500 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
24510 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
24520 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
24530 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
24540 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
24550 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24560 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
24570 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
24580 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
24590 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
245a0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
245b0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
245c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
245d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
245e0 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
245f0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
24600 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24610 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
24620 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
24630 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24640 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
24650 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
24660 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
24670 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
24680 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
24690 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
246a0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
246b0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
246c0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
246d0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
246e0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
246f0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
24700 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
24710 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
24720 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
24730 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
24740 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
24750 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
24760 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
24770 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
24780 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
24790 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69  eturned.** [sqli
247a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
247b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  )], [sqlite3_col
247c0 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63  umn_text()], etc
247d0 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  . into.** [sqlit
247e0 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
247f0 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20  * ^(If a memory 
24800 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
24810 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74   occurs during t
24820 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  he evaluation of
24830 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65   any.** of these
24840 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66   routines, a def
24850 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65  ault value is re
24860 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66  turned.  The def
24870 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73  ault value.** is
24880 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65   either the inte
24890 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74  ger 0, the float
248a0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
248b0 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a   0.0, or a NULL.
248c0 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62  ** pointer.  Sub
248d0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
248e0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
248f0 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  e()] will return
24900 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .** [SQLITE_NOME
24910 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  M].)^.*/.const v
24920 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
24930 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
24940 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24950 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
24960 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
24970 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
24980 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
24990 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
249a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
249b0 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c  int iCol);.doubl
249c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
249d0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
249e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
249f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
24a00 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
24a10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24a20 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
24a30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24a40 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
24a50 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24a60 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
24a70 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
24a80 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
24a90 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
24aa0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
24ab0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24ac0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
24ad0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
24ae0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
24af0 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
24b00 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24b10 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a  .sqlite3_value *
24b20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
24b30 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
24b40 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
24b50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24b60 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
24b70 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
24b80 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
24b90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24ba0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
24bb0 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
24bc0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24bd0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
24be0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
24bf0 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73 73  executed success
24c00 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78 65  fully or not exe
24c10 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74 68  cuted at all, th
24c20 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 20  en.** SQLITE_OK 
24c30 69 73 20 72 65 74 75 72 6e 65 64 2e 20 5e 49 66  is returned. ^If
24c40 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
24c50 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69 6c  e statement fail
24c60 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b 65  ed then an.** [e
24c70 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b 65  rror code] or [e
24c80 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
24c90 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
24ca0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
24cb0 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
24cc0 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
24cd0 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63 75  during the execu
24ce0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  tion of the.** [
24cf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24d00 6e 74 5d 2e 20 20 5e 49 66 20 74 68 65 20 76 69  nt].  ^If the vi
24d10 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68 61  rtual machine ha
24d20 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s not.** complet
24d30 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68 65  ed execution whe
24d40 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  n this routine i
24d50 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20 69  s called, that i
24d60 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75 6e  s like.** encoun
24d70 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72 20  tering an error 
24d80 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  or an [sqlite3_i
24d90 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65 72  nterrupt | inter
24da0 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f 6d  rupt]..** ^Incom
24db0 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d 61  plete updates ma
24dc0 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  y be rolled back
24dd0 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f 6e   and transaction
24de0 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20 64  s canceled,.** d
24df0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
24e00 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 61  circumstances, a
24e10 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f 72  nd the.** [error
24e20 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64 20   code] returned 
24e30 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45 5f  will be [SQLITE_
24e40 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ABORT]..*/.int s
24e50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24e60 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
24e70 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
24e80 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
24e90 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
24ea0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
24eb0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
24ec0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
24ed0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
24ee0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24ef0 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
24f00 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
24f10 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
24f20 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
24f30 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
24f40 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
24f50 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
24f60 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
24f70 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
24f80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
24f90 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
24fa0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
24fb0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
24fc0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
24fd0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
24fe0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
24ff0 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
25000 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
25010 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
25020 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
25030 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25040 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
25050 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
25060 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
25070 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
25080 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
25090 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
250a0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
250b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
250c0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
250d0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
250e0 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
250f0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
25100 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
25110 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
25120 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
25130 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
25140 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
25150 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
25160 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
25170 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
25180 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
25190 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
251a0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
251b0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
251c0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
251d0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
251e0 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
251f0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
25200 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
25210 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
25220 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
25230 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
25240 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
25250 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
25260 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
25270 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
25280 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
25290 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
252a0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
252b0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
252c0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
252d0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
252e0 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
252f0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
25300 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
25310 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
25320 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
25330 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
25340 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
25350 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
25360 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
25370 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 74  }.**.** ^These t
25380 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  wo functions (co
25390 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
253a0 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
253b0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
253c0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
253d0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
253e0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
253f0 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
25400 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
25410 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
25420 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
25430 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
25440 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62 65  ly difference be
25450 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77 6f  tween the.** two
25460 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65 63   is that the sec
25470 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20 74  ond parameter, t
25480 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 28  he name of the (
25490 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f 6e  scalar) function
254a0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
254b0 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e 20  , is encoded in 
254c0 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74 65  UTF-8 for sqlite
254d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
254e0 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a 2a  n() and UTF-16.*
254f0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
25500 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
25510 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  )..**.** ^The fi
25520 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
25530 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
25540 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
25550 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
25560 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
25570 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
25580 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
25590 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
255a0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
255b0 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
255c0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
255d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
255e0 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
255f0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
25600 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
25610 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tely..**.** The 
25620 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
25630 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
25640 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
25650 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
25660 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
25670 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
25680 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
25690 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
256a0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a 2a  , exclusive of.*
256b0 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  * the zero-termi
256c0 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68 61  nator.  Note tha
256d0 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67 74  t the name lengt
256e0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62 79  h limit is in by
256f0 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61 72  tes, not.** char
25700 61 63 74 65 72 73 2e 20 20 5e 41 6e 79 20 61 74  acters.  ^Any at
25710 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
25720 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
25730 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
25740 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
25750 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 62  [SQLITE_ERROR] b
25760 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
25770 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
25780 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
25790 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
257a0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
257b0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
257c0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
257d0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
257e0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
257f0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
25800 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
25810 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
25820 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
25830 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
25840 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
25850 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
25860 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
25870 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
25880 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
25890 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
258a0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
258b0 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
258c0 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
258d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
258e0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
258f0 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68 20  *.** The fourth 
25900 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
25910 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
25920 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
25930 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
25940 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
25950 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
25960 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
25970 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20 66  ters.  Any SQL f
25980 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
25990 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  tation should be
259a0 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
259b0 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d 38   work with UTF-8
259c0 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
259d0 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
259e0 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
259f0 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
25a00 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
25a10 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
25a20 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e  an another.  ^An
25a30 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
25a40 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
25a50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
25a60 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
25a70 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
25a80 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  6() multiple.** 
25a90 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
25aa0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74  ame function but
25ab0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
25ac0 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52  values of eTextR
25ad0 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c  ep..** ^When mul
25ae0 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
25af0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
25b00 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
25b10 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
25b20 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
25b30 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
25b40 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
25b50 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
25b60 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
25b70 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
25b80 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
25b90 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
25ba0 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65  not care what te
25bb0 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69  xt.** encoding i
25bc0 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
25bd0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
25be0 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49   should be [SQLI
25bf0 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  TE_ANY]..**.** ^
25c00 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
25c10 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
25c20 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
25c30 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
25c40 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
25c50 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
25c60 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
25c70 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
25c80 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
25c90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  .)^.**.** The se
25ca0 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61 6e  venth, eighth an
25cb0 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  d ninth paramete
25cc0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
25cd0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
25ce0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
25cf0 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
25d00 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
25d10 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
25d20 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
25d30 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
25d40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
25d50 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
25d60 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
25d70 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
25d80 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
25d90 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 70  ters should be p
25da0 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74  assed as the xSt
25db0 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a  ep and xFinal.**
25dc0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e   parameters. ^An
25dd0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
25de0 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
25df0 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
25e00 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61  on of xStep.** a
25e10 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55  nd xFinal and NU
25e20 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61 73  LL should be pas
25e30 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
25e40 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
25e50 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
25e60 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
25e70 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66 6f  te, pass NULL fo
25e80 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
25e90 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  tion callbacks..
25ea0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
25eb0 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
25ec0 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
25ed0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
25ee0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
25ef0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
25f00 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
25f10 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
25f20 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
25f30 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
25f40 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
25f50 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
25f60 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
25f70 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
25f80 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
25f90 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
25fa0 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
25fb0 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
25fc0 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
25fd0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
25fe0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
25ff0 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
26000 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
26010 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
26020 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
26030 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
26040 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
26050 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
26060 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
26070 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
26080 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
26090 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
260a0 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
260b0 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
260c0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
260d0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
260e0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
260f0 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
26100 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
26110 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
26120 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
26130 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
26140 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
26150 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
26160 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
26170 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
26180 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
26190 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
261a0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
261b0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
261c0 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
261d0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
261e0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
261f0 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ns..** ^The firs
26200 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  t application-de
26210 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 77  fined function w
26220 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d 65  ith a given name
26230 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a 2a   overrides all.*
26240 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74  * built-in funct
26250 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d 65  ions in the same
26260 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
26270 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65 20  ction] with the 
26280 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 53  same name..** ^S
26290 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69 63  ubsequent applic
262a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
262b0 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  nctions of the s
262c0 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f 76  ame name only ov
262d0 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f 72  erride .** prior
262e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
262f0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20 74  ined functions t
26300 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63 74  hat are an exact
26310 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a 2a   match for the.*
26320 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72 61  * number of para
26330 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66 65  meters and prefe
26340 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  rred encoding..*
26350 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
26360 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
26370 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
26380 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
26390 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
263a0 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
263b0 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
263c0 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
263d0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
263e0 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
263f0 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
26400 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
26410 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
26420 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
26430 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
26440 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
26450 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
26460 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
26470 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
26480 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
26490 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
264a0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
264b0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
264c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
264d0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
264e0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
264f0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
26500 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
26510 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
26520 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
26530 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
26540 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
26550 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
26560 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
26570 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
26580 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
26590 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
265a0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
265b0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
265c0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
265d0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
265e0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
265f0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
26600 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
26610 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
26620 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
26630 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
26640 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  ntext*).);../*.*
26650 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
26660 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
26670 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
26680 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
26690 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
266a0 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
266b0 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
266c0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
266d0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
266e0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
266f0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
26700 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
26710 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
26720 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
26730 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
26740 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
26750 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
26760 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
26770 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
26780 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
26790 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
267a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
267b0 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
267c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
267d0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
267e0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
267f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
26800 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
26810 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
26820 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
26830 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
26840 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
26850 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
26860 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
26870 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
26880 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
26890 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
268a0 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
268b0 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
268c0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
268d0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
268e0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
268f0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
26900 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
26910 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
26920 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
26930 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
26940 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
26950 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
26960 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
26970 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
26980 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
26990 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
269a0 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
269b0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
269c0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
269d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
269e0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
269f0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
26a00 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
26a10 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
26a20 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
26a30 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
26a40 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
26a50 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
26a60 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
26a70 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
26a80 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
26a90 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
26aa0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
26ab0 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
26ac0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
26ad0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
26ae0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
26af0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
26b00 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
26b10 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
26b20 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
26b30 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
26b40 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
26b50 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
26b60 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
26b70 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
26b80 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
26b90 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
26ba0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
26bb0 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
26bc0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
26bd0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
26be0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
26bf0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
26c00 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
26c10 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
26c20 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
26c30 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
26c40 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
26c50 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
26c60 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
26c70 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26c80 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
26c90 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
26ca0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
26cb0 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
26cc0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
26cd0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
26ce0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
26cf0 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20 70  es..** The 4th p
26d00 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
26d10 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
26d20 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
26d30 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
26d40 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
26d50 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
26d60 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
26d70 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26d80 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
26d90 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
26da0 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
26db0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
26dc0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
26dd0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
26de0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
26df0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
26e00 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
26e10 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
26e20 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
26e30 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
26e40 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
26e50 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
26e60 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
26e70 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
26e80 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
26e90 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
26ea0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
26eb0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
26ec0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
26ed0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
26ee0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
26ef0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
26f00 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
26f10 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
26f20 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
26f30 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
26f40 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26f50 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
26f60 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
26f70 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
26f80 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
26f90 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
26fa0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26fb0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
26fc0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
26fd0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
26fe0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
26ff0 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
27000 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
27010 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
27020 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
27030 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
27040 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
27050 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
27060 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
27070 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
27080 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
27090 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
270a0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
270b0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
270c0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
270d0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
270e0 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
270f0 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
27100 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
27110 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
27120 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
27130 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
27140 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
27150 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
27160 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
27170 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
27180 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
27190 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
271a0 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
271b0 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
271c0 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
271d0 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
271e0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
271f0 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
27200 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
27210 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
27220 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
27230 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
27240 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
27250 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
27260 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
27270 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
27280 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
27290 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
272a0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
272b0 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
272c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
272d0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
272e0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
272f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
27300 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
27310 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
27320 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
27330 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
27340 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
27350 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
27360 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
27370 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
27380 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
27390 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
273a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
273b0 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
273c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
273d0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
273e0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
273f0 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
27400 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
27410 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
27420 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
27430 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
27440 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
27450 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
27460 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
27470 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
27480 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
27490 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
274a0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
274b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
274c0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
274d0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
274e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
274f0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
27500 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
27510 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
27520 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
27530 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
27540 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
27550 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
27560 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
27570 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
27580 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
27590 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
275a0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
275b0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
275c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
275d0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
275e0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
275f0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
27600 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
27610 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
27620 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
27630 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
27640 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
27650 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
27660 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
27670 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27680 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
27690 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
276a0 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
276b0 65 6d 65 6e 74 69 6f 6e 73 20 6f 66 20 61 67 67  ementions of agg
276c0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
276d0 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
276e0 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
276f0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
27700 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
27710 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
27720 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
27730 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
27740 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
27750 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
27760 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
27770 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
27780 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
27790 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
277a0 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
277b0 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
277c0 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
277d0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
277e0 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
277f0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
27800 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
27810 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
27820 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
27830 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
27840 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
27850 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
27860 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
27870 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
27880 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
27890 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
278a0 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
278b0 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
278c0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
278d0 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
278e0 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
278f0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
27900 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
27910 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
27920 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
27930 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
27940 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
27950 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
27960 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
27970 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
27980 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
27990 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
279a0 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
279b0 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
279c0 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
279d0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
279e0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
279f0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
27a00 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
27a10 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
27a20 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
27a30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
27a40 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
27a50 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
27a60 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
27a70 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c  ter if N is.** l
27a80 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
27a90 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
27aa0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
27ab0 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
27ac0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
27ad0 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
27ae0 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
27af0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27b00 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
27b10 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
27b20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
27b30 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
27b40 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
27b50 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
27b60 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
27b70 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
27b80 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
27b90 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
27ba0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
27bb0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
27bc0 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
27bd0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
27be0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a   allocation.)^.*
27bf0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
27c00 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
27c10 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
27c20 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
27c30 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
27c40 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
27c50 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
27c60 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
27c70 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
27c80 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
27c90 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
27ca0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
27cb0 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
27cc0 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
27cd0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
27ce0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
27cf0 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
27d00 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
27d10 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
27d20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
27d30 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
27d40 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
27d50 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
27d60 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
27d70 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
27d80 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
27d90 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
27da0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
27db0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27dc0 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
27dd0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
27de0 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
27df0 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
27e00 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
27e10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27e20 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
27e30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
27e40 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
27e50 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
27e60 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
27e70 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
27e80 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
27e90 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
27ea0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
27eb0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
27ec0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
27ed0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
27ee0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
27ef0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
27f00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
27f10 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
27f20 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
27f30 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
27f40 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
27f50 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
27f60 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
27f70 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
27f80 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
27f90 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
27fa0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
27fb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
27fc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27fd0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
27fe0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
27ff0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
28000 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
28010 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
28020 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
28030 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
28040 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
28050 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28060 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
28070 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
28080 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
28090 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
280a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
280b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
280c0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
280d0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
280e0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
280f0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
28100 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71   function..*/.sq
28110 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
28120 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
28130 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
28140 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
28150 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
28160 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
28170 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
28180 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
28190 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
281a0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
281b0 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
281c0 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
281d0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
281e0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
281f0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
28200 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
28210 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
28220 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
28230 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
28240 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
28250 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
28260 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
28270 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
28280 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
28290 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
282a0 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
282b0 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
282c0 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
282d0 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
282e0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
282f0 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
28300 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
28310 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
28320 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
28330 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
28340 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
28350 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
28360 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
28370 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
28380 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
28390 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
283a0 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
283b0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
283c0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
283d0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
283e0 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
283f0 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
28400 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
28410 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
28420 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
28430 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
28440 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
28450 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
28460 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
28470 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
28480 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
28490 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
284a0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
284b0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
284c0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
284d0 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
284e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
284f0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
28500 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
28510 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
28520 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
28530 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
28540 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
28550 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
28560 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
28570 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
28580 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
28590 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
285a0 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
285b0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
285c0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
285d0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
285e0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
285f0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
28600 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
28610 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
28620 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
28630 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
28640 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
28650 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
28660 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
28670 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
28680 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
28690 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
286a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
286b0 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
286c0 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
286d0 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
286e0 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
286f0 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
28700 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
28710 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
28720 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
28730 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
28740 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
28750 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
28760 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
28770 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
28780 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
28790 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
287a0 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
287b0 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
287c0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
287d0 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
287e0 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
287f0 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
28800 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
28810 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
28820 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
28830 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
28840 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
28850 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
28860 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
28870 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
28880 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
28890 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
288a0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
288b0 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
288c0 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
288d0 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
288e0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
288f0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
28900 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
28910 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
28920 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
28930 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
28940 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
28950 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
28960 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
28970 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
28980 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
28990 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
289a0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
289b0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
289c0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
289d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
289e0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
289f0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
28a00 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
28a10 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
28a20 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
28a30 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
28a40 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
28a50 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
28a60 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
28a70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
28a80 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
28a90 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
28aa0 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
28ab0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
28ac0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
28ad0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
28ae0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
28af0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
28b00 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
28b10 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
28b20 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
28b30 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
28b40 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
28b50 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
28b60 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
28b70 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
28b80 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
28b90 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
28ba0 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
28bb0 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
28bc0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
28bd0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
28be0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
28bf0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
28c00 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
28c10 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
28c20 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
28c30 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
28c40 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
28c50 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
28c60 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
28c70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
28c80 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
28c90 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
28ca0 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
28cb0 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b  ilers.  See tick
28cc0 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70  et #2191..*/.typ
28cd0 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
28ce0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
28cf0 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
28d00 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
28d10 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
28d20 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
28d30 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
28d40 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
28d50 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
28d60 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
28d70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
28d80 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
28d90 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
28da0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
28db0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
28dc0 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
28dd0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
28de0 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
28df0 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
28e00 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
28e10 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
28e20 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28e30 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
28e40 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28e50 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
28e60 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
28e70 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
28e80 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
28e90 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
28ea0 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
28eb0 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
28ec0 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
28ed0 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
28ee0 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
28ef0 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
28f00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
28f10 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
28f20 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
28f30 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
28f40 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
28f50 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
28f60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
28f70 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
28f80 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
28f90 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
28fa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
28fb0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
28fc0 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
28fd0 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
28fe0 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
28ff0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
29000 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
29010 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
29020 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
29030 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
29040 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29050 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
29060 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
29070 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
29080 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
29090 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
290a0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
290b0 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
290c0 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
290d0 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
290e0 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
290f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
29100 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
29110 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29120 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
29130 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
29140 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
29150 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
29160 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29170 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
29180 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
29190 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
291a0 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
291b0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
291c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
291d0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
291e0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
291f0 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
29200 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
29210 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
29220 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
29230 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
29240 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
29250 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
29260 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
29270 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
29280 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29290 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
292a0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
292b0 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
292c0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
292d0 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
292e0 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
292f0 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
29300 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
29310 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
29320 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
29330 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
29340 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
29350 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29360 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
29370 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
29380 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
29390 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
293a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
293b0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
293c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
293d0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
293e0 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
293f0 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
29400 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
29410 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
29420 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
29430 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
29440 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
29450 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
29460 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29470 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
29480 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29490 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
294a0 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
294b0 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
294c0 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
294d0 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
294e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
294f0 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
29500 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
29510 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29520 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
29530 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
29540 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
29550 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
29560 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
29570 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
29580 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
29590 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
295a0 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
295b0 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
295c0 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
295d0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
295e0 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
295f0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
29600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
29610 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
29620 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
29630 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
29640 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
29650 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
29660 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
29670 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
29680 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
29690 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
296a0 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
296b0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
296c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
296d0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
296e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
296f0 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
29700 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
29710 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
29720 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29730 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20  result_toobig() 
29740 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
29750 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
29760 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
29770 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73  icating that a s
29780 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73  tring or BLOB is
29790 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70   too long to rep
297a0 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  resent..**.** ^T
297b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
297c0 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  t_nomem() interf
297d0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
297e0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72  e to throw an er
297f0 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e  ror.** indicatin
29800 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
29810 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
29820 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
29830 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
29840 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
29850 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
29860 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
29870 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29880 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
29890 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
298a0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
298b0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
298c0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
298d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
298e0 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
298f0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
29900 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
29910 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
29920 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
29930 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
29940 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
29950 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
29960 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
29970 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
29980 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
29990 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
299a0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
299b0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
299c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
299d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
299e0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
299f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
29a00 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
29a10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29a20 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
29a30 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
29a40 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
29a50 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
29a60 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
29a70 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
29a80 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
29a90 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
29aa0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
29ab0 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
29ac0 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
29ad0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
29ae0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
29af0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
29b00 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
29b10 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
29b20 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
29b30 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
29b40 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
29b50 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
29b60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
29b70 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
29b80 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
29b90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
29ba0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
29bb0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
29bc0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
29bd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
29be0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
29bf0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
29c00 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
29c10 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
29c20 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
29c30 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
29c40 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
29c50 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
29c60 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
29c70 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
29c80 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
29c90 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
29ca0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
29cb0 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
29cc0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
29cd0 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
29ce0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
29cf0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
29d00 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
29d10 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29d20 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
29d30 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
29d40 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
29d50 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
29d60 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
29d70 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
29d80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
29d90 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
29da0 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
29db0 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
29dc0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
29dd0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
29de0 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
29df0 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
29e00 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
29e10 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
29e20 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
29e30 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
29e40 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
29e50 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
29e60 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
29e70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
29e80 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
29e90 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
29ea0 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
29eb0 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
29ec0 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
29ed0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
29ee0 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
29ef0 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
29f00 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
29f10 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
29f20 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
29f30 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
29f40 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
29f50 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
29f60 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
29f70 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
29f80 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
29f90 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
29fa0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
29fb0 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
29fc0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
29fd0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
29fe0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
29ff0 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
2a000 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
2a010 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
2a020 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
2a030 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
2a040 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
2a050 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
2a060 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2a070 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2a080 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
2a090 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2a0a0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
2a0b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2a0c0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2a0d0 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
2a0e0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2a0f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2a100 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
2a110 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2a120 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
2a130 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2a140 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
2a150 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2a160 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
2a170 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
2a180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
2a190 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
2a1a0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
2a1b0 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
2a1c0 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
2a1d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2a1e0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
2a1f0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
2a200 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
2a210 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2a220 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
2a230 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
2a240 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2a250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2a260 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
2a270 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
2a280 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
2a290 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
2a2a0 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
2a2b0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
2a2c0 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
2a2d0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2a2e0 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
2a2f0 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
2a300 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
2a310 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
2a320 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2a330 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2a340 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
2a350 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2a360 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
2a370 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2a380 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
2a390 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2a3a0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
2a3b0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2a3c0 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2a3d0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2a3e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a3f0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
2a400 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
2a410 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2a420 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
2a430 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2a440 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
2a450 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2a460 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
2a470 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2a480 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
2a490 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2a4a0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
2a4b0 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
2a4c0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
2a4d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2a4e0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
2a4f0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2a500 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2a510 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
2a520 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
2a530 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a540 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
2a550 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
2a560 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2a570 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
2a580 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
2a590 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
2a5a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a5b0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
2a5c0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2a5d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a5e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a5f0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
2a600 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2a610 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2a620 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2a630 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2a640 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2a650 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2a660 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2a670 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2a680 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2a690 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2a6a0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
2a6b0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2a6c0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2a6d0 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
2a6e0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2a6f0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
2a700 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2a710 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2a720 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2a730 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
2a740 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
2a750 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
2a760 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
2a770 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
2a780 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
2a790 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
2a7a0 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
2a7b0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
2a7c0 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  s are used to ad
2a7d0 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  d new collation 
2a7e0 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68 65  sequences to the
2a7f0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
2a800 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
2a810 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
2a820 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2a830 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
2a840 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e 20  e new collation 
2a850 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65 63  sequence is spec
2a860 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d 38  ified as a UTF-8
2a870 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
2a880 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a890 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
2a8a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2a8b0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
2a8c0 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
2a8d0 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ng for sqlite3_c
2a8e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2a8f0 36 28 29 2e 20 5e 49 6e 20 61 6c 6c 20 63 61 73  6(). ^In all cas
2a900 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 69  es.** the name i
2a910 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  s passed as the 
2a920 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
2a930 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2a940 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
2a950 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ent may be one o
2a960 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 20  f the constants 
2a970 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a  [SQLITE_UTF8],.*
2a980 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
2a990 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
2a9a0 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61 74  TF16BE], indicat
2a9b0 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73 65  ing that the use
2a9c0 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72 6f  r-supplied.** ro
2a9d0 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74 6f  utine expects to
2a9e0 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e 74   be passed point
2a9f0 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 65  ers to strings e
2aa00 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
2aa10 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69  -8,.** UTF-16 li
2aa20 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72 20  ttle-endian, or 
2aa30 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69 61  UTF-16 big-endia
2aa40 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
2aa50 20 5e 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 61   ^The.** third a
2aa60 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61 6c  rgument might al
2aa70 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55 54  so be [SQLITE_UT
2aa80 46 31 36 5d 20 74 6f 20 69 6e 64 69 63 61 74 65  F16] to indicate
2aa90 20 74 68 61 74 20 74 68 65 20 72 6f 75 74 69 6e   that the routin
2aaa0 65 0a 2a 2a 20 65 78 70 65 63 74 73 20 70 6f 69  e.** expects poi
2aab0 6e 74 65 72 73 20 74 6f 20 62 65 20 55 54 46 2d  nters to be UTF-
2aac0 31 36 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  16 strings in th
2aad0 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2aae0 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20 61  der, or the.** a
2aaf0 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65 20 5b  rgument can be [
2ab00 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2ab10 47 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a 20  GNED] if the.** 
2ab20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70 65  the routine expe
2ab30 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  cts pointers to 
2ab40 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69 67  16-bit word alig
2ab50 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 6f  ned strings.** o
2ab60 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  f UTF-16 in the 
2ab70 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2ab80 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74  r..**.** A point
2ab90 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 20 73  er to the user s
2aba0 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65 20  upplied routine 
2abb0 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
2abc0 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20 61  s the fifth.** a
2abd0 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 69 74  rgument.  ^If it
2abe0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20 69   is NULL, this i
2abf0 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64 65  s the same as de
2ac00 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c 61  leting the colla
2ac10 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2ac20 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65   (so that SQLite
2ac30 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74 20   cannot call it 
2ac40 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45 61  anymore)..** ^Ea
2ac50 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70 6c  ch time the appl
2ac60 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64  ication supplied
2ac70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
2ac80 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73 73  oked, it is pass
2ac90 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69 72  ed.** as its fir
2aca0 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20 63  st parameter a c
2acb0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
2acc0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
2acd0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
2ace0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  * to sqlite3_cre
2acf0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
2ad00 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2ad10 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
2ad20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 6d 61  .**.** ^The rema
2ad30 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73 20  ining arguments 
2ad40 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
2ad50 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75 74  on-supplied rout
2ad60 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72 69  ine are two stri
2ad70 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65 70  ngs,.** each rep
2ad80 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28 6c  resented by a (l
2ad90 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61 69  ength, data) pai
2ada0 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69 6e  r and encoded in
2adb0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a   the encoding.**
2adc0 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64   that was passed
2add0 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61 72   as the third ar
2ade0 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65 20  gument when the 
2adf0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2ae00 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73 74  ce was.** regist
2ae10 65 72 65 64 2e 20 20 54 68 65 20 61 70 70 6c 69  ered.  The appli
2ae20 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 63  cation defined c
2ae30 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  ollation routine
2ae40 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
2ae50 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f  n negative, zero
2ae60 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66 20   or positive if 
2ae70 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
2ae80 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a 2a   is less than,.*
2ae90 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  * equal to, or g
2aea0 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
2aeb0 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20 69  second string. i
2aec0 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20 53  .e. (STRING1 - S
2aed0 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20 5e  TRING2)..**.** ^
2aee0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
2aef0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2af00 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  ) works like sql
2af10 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2af20 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65 70  ation().** excep
2af30 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73 20  t that it takes 
2af40 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65 6e  an extra argumen
2af50 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65 73  t which is a des
2af60 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20 74  tructor for.** t
2af70 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20 5e  he collation.  ^
2af80 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2af90 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  s called when th
2afa0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a 2a  e collation is.*
2afb0 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20  * destroyed and 
2afc0 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70 79  is passed a copy
2afd0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
2afe0 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20 70  arameter void* p
2aff0 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68 65  ointer.** of the
2b000 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2b010 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e 0a  collation_v2()..
2b020 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20 61  ** ^Collations a
2b030 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 68 65  re destroyed whe
2b040 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
2b050 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20 63  idden by later c
2b060 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 63  alls to the.** c
2b070 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
2b080 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
2b090 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73  hen the [databas
2b0a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
2b0b0 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e 67   closed.** using
2b0c0 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
2b0d0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2b0e0 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f  so:  [sqlite3_co
2b0f0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2b100 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
2b110 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2b120 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  6()]..*/.int sql
2b130 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2b140 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  ation(.  sqlite3
2b150 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
2b160 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
2b170 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
2b180 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  d*,.  int(*xComp
2b190 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2b1a0 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2b1b0 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 69  onst void*).);.i
2b1c0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2b1d0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a  e_collation_v2(.
2b1e0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63    sqlite3*, .  c
2b1f0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2b200 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  , .  int eTextRe
2b210 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 69  p, .  void*,.  i
2b220 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
2b230 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2b240 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2b250 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
2b260 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
2b270 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
2b280 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
2b290 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2b2a0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
2b2b0 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
2b2c0 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2b2d0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2b2e0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2b2f0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2b300 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
2b310 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
2b320 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
2b330 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
2b340 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
2b350 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
2b360 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
2b370 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
2b380 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
2b390 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
2b3a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
2b3b0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
2b3c0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
2b3d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2b3e0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
2b3f0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
2b400 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
2b410 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
2b420 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
2b430 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
2b440 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
2b450 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
2b460 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2b470 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
2b480 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
2b490 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
2b4a0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
2b4b0 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
2b4c0 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
2b4d0 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
2b4e0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2b4f0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
2b500 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
2b510 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
2b520 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
2b530 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
2b540 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
2b550 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
2b560 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
2b570 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
2b580 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
2b590 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
2b5a0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
2b5b0 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
2b5c0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
2b5d0 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
2b5e0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2b5f0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
2b600 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2b610 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2b620 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2b630 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
2b640 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2b650 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
2b660 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
2b670 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2b680 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
2b690 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
2b6a0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
2b6b0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
2b6c0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
2b6d0 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
2b6e0 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
2b6f0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2b700 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
2b710 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
2b720 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b730 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
2b740 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
2b750 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
2b760 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
2b770 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
2b780 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
2b790 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
2b7a0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2b7b0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2b7c0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
2b7d0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2b7e0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
2b7f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2b800 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
2b810 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
2b820 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
2b830 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2b840 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
2b850 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
2b860 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
2b870 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
2b880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2b890 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
2b8a0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
2b8b0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
2b8c0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
2b8d0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
2b8e0 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
2b8f0 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
2b900 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
2b910 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
2b920 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
2b930 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
2b940 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
2b950 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
2b960 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
2b970 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
2b980 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
2b990 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
2b9a0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
2b9b0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
2b9c0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
2b9d0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
2b9e0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2b9f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ba00 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2ba10 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2ba20 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2ba30 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2ba40 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
2ba50 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
2ba60 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
2ba70 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
2ba80 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
2ba90 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
2baa0 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
2bab0 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
2bac0 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
2bad0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
2bae0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
2baf0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
2bb00 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2bb10 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2bb20 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2bb30 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2bb40 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2bb50 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
2bb60 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
2bb70 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2bb80 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2bb90 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
2bba0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
2bbb0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
2bbc0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
2bbd0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
2bbe0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
2bbf0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
2bc00 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
2bc10 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
2bc20 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
2bc30 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
2bc40 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
2bc50 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2bc60 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
2bc70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
2bc80 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
2bc90 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
2bca0 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
2bcb0 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
2bcc0 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
2bcd0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
2bce0 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
2bcf0 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
2bd00 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
2bd10 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
2bd20 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
2bd30 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
2bd40 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2bd50 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64  3_activate_cerod
2bd60 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
2bd70 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
2bd80 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
2bd90 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
2bda0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2bdb0 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
2bdc0 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
2bdd0 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ort Time.**.** ^
2bde0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
2bdf0 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
2be00 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
2be10 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
2be20 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
2be30 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
2be40 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2be50 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
2be60 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
2be70 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f  .**.** ^If the o
2be80 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
2be90 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  does not support
2bea0 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20   sleep requests 
2beb0 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63  with.** millisec
2bec0 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74  ond time resolut
2bed0 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69  ion, then the ti
2bee0 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64  me will be round
2bef0 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20  ed up to.** the 
2bf00 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20  nearest second. 
2bf10 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  ^The number of m
2bf20 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
2bf30 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  leep actually.**
2bf40 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20   requested from 
2bf50 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
2bf60 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64  stem is returned
2bf70 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
2bf80 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20  implements this 
2bf90 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61 6c  interface by cal
2bfa0 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28  ling the xSleep(
2bfb0 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74  ).** method of t
2bfc0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
2bfd0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
2bfe0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2bff0 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
2c000 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2c010 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
2c020 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
2c030 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
2c040 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
2c050 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
2c060 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
2c070 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
2c080 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
2c090 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
2c0a0 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
2c0b0 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
2c0c0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
2c0d0 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
2c0e0 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
2c0f0 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
2c100 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
2c110 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
2c120 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
2c130 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2c140 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2c150 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
2c160 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
2c170 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
2c180 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
2c190 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
2c1a0 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
2c1b0 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
2c1c0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2c1d0 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
2c1e0 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
2c1f0 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
2c200 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
2c210 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
2c220 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
2c230 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2c240 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
2c250 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
2c260 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
2c270 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
2c280 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
2c290 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
2c2a0 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
2c2b0 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
2c2c0 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
2c2d0 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
2c2e0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
2c2f0 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
2c300 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
2c310 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
2c320 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
2c330 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
2c340 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
2c350 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72   ^The [temp_stor
2c360 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2c370 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
2c380 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
2c390 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
2c3a0 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
2c3b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2c3c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
2c3d0 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
2c3e0 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * the [temp_stor
2c3f0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2c400 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
2c410 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
2c420 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
2c430 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
2c440 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
2c450 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2c460 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
2c470 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
2c480 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
2c490 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
2c4a0 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
2c4b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
2c4c0 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
2c4d0 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
2c4e0 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
2c4f0 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
2c500 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
2c510 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
2c520 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
2c530 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2c540 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
2c550 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
2c560 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  f the [temp_stor
2c570 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2c580 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
2c590 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oided..*/.SQLITE
2c5a0 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
2c5b0 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
2c5c0 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
2c5d0 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
2c5e0 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
2c5f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2c600 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
2c610 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c620 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
2c630 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
2c640 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
2c650 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
2c660 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
2c670 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
2c680 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
2c690 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
2c6a0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41  espectively.  ^A
2c6b0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2c6c0 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
2c6d0 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
2c6e0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
2c6f0 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
2c700 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74  atement..** ^Aut
2c710 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2c720 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
2c730 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
2c740 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
2c750 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
2c760 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
2c770 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
2c780 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
2c790 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
2c7a0 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
2c7b0 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
2c7c0 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
2c7d0 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
2c7e0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
2c7f0 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
2c800 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
2c810 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
2c820 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
2c830 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
2c840 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
2c850 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
2c860 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
2c870 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
2c880 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2c890 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2c8a0 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
2c8b0 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
2c8c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
2c8d0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
2c8e0 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
2c8f0 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
2c900 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
2c910 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2c920 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
2c930 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
2c940 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
2c950 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64   value.** is und
2c960 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
2c970 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
2c980 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
2c990 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2c9a0 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62  : Find The Datab
2c9b0 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
2c9c0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2c9d0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  nt.**.** ^The sq
2c9e0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
2c9f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ca00 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
2ca10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
2ca20 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
2ca30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ca40 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
2ca50 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63  ^The [database c
2ca60 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65  onnection].** re
2ca70 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2ca80 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
2ca90 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2caa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
2cab0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
2cac0 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
2cad0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2cae0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
2caf0 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
2cb00 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
2cb10 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
2cb20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
2cb30 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
2cb40 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
2cb50 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
2cb60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2cb70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cb80 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
2cb90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cba0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
2cbb0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2cbc0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2cbd0 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
2cbe0 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
2cbf0 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
2cc00 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
2cc10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2cc20 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
2cc30 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
2cc40 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
2cc50 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2cc60 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
2cc70 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
2cc80 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
2cc90 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
2cca0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2ccb0 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
2ccc0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2ccd0 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
2cce0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
2ccf0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
2cd00 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
2cd10 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
2cd20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
2cd30 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
2cd40 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2cd50 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
2cd60 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
2cd70 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
2cd80 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
2cd90 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
2cda0 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
2cdb0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73  LL pointer..*/.s
2cdc0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
2cdd0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
2cde0 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
2cdf0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2ce00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ce10 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
2ce20 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
2ce30 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
2ce40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ce50 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
2ce60 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2ce70 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
2ce80 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
2ce90 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2cea0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
2ceb0 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
2cec0 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
2ced0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2cee0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2cef0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
2cf00 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
2cf10 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2cf20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2cf30 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2cf40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
2cf50 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
2cf60 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2cf70 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
2cf80 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
2cf90 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2cfa0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2cfb0 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
2cfc0 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
2cfd0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2cfe0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2cff0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
2d000 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
2d010 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
2d020 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d030 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
2d040 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
2d050 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
2d060 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
2d070 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
2d080 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
2d090 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
2d0a0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
2d0b0 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
2d0c0 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
2d0d0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2d0e0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2d0f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
2d100 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
2d110 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
2d120 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
2d130 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
2d140 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
2d150 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
2d160 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
2d170 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
2d180 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
2d190 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d1a0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
2d1b0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
2d1c0 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
2d1d0 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
2d1e0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
2d1f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2d200 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2d210 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2d220 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2d230 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2d240 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2d250 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
2d260 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
2d270 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2d280 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
2d290 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
2d2a0 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
2d2b0 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
2d2c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2d2d0 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
2d2e0 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
2d2f0 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
2d300 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
2d310 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
2d320 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
2d330 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2d340 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
2d350 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
2d360 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
2d370 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
2d380 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
2d390 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
2d3a0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
2d3b0 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67  .** ^Registering
2d3c0 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
2d3d0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
2d3e0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57  llback..**.** ^W
2d3f0 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
2d400 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  ook callback rou
2d410 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
2d420 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a  o, the [COMMIT].
2d430 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ** operation is 
2d440 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69  allowed to conti
2d450 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e  nue normally.  ^
2d460 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  If the commit ho
2d470 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f  ok.** returns no
2d480 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
2d490 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e   [COMMIT] is con
2d4a0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52  verted into a [R
2d4b0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68  OLLBACK]..** ^Th
2d4c0 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  e rollback hook 
2d4d0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20  is invoked on a 
2d4e0 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65  rollback that re
2d4f0 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d  sults from a com
2d500 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75  mit.** hook retu
2d510 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  rning non-zero, 
2d520 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64  just as it would
2d530 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68   be with any oth
2d540 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  er rollback..**.
2d550 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
2d560 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
2d570 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
2d580 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
2d590 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
2d5a0 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
2d5b0 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
2d5c0 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
2d5d0 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
2d5e0 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
2d5f0 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
2d600 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
2d610 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20   occur..** ^The 
2d620 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
2d630 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
2d640 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
2d650 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
2d660 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
2d670 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
2d680 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d690 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
2d6a0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
2d6b0 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
2d6c0 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
2d6d0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
2d6e0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2d6f0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
2d700 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
2d710 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
2d720 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
2d730 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
2d740 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
2d750 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d760 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
2d770 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2d780 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
2d790 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2d7a0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2d7b0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2d7c0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
2d7d0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
2d7e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2d7f0 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2d800 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
2d810 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2d820 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
2d830 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2d840 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2d850 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
2d860 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2d870 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
2d880 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
2d890 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2d8a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d8b0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
2d8c0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2d8d0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2d8e0 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
2d8f0 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
2d900 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20  hen a.** row is 
2d910 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
2d920 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
2d930 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2d940 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
2d950 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
2d960 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
2d970 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
2d980 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2d990 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  ..** ^The second
2d9a0 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
2d9b0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2d9c0 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
2d9d0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
2d9e0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
2d9f0 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
2da00 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
2da10 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
2da20 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
2da30 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  be invoked..** ^
2da40 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2da50 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
2da60 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
2da70 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
2da80 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
2da90 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
2daa0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2dab0 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
2dac0 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  * ^The final cal
2dad0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
2dae0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
2daf0 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49  f the row..** ^I
2db00 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
2db10 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
2db20 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74   the [rowid] aft
2db30 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61  er the update ta
2db40 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
2db50 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f   ^(The update ho
2db60 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
2db70 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
2db80 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
2db90 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
2dba0 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
2dbb0 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
2dbc0 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  uence).)^.**.** 
2dbd0 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  ^In the current 
2dbe0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
2dbf0 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
2dc00 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ** is not invoke
2dc10 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69  d when duplicati
2dc20 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  on rows are dele
2dc30 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61  ted because of a
2dc40 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  n.** [ON CONFLIC
2dc50 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  T | ON CONFLICT 
2dc60 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e  REPLACE] clause.
2dc70 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70    ^Nor is the up
2dc80 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76  date hook.** inv
2dc90 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61  oked when rows a
2dca0 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  re deleted using
2dcb0 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f   the [truncate o
2dcc0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a  ptimization]..**
2dcd0 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20   The exceptions 
2dce0 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20  defined in this 
2dcf0 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20  paragraph might 
2dd00 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
2dd10 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
2dd20 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
2dd30 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
2dd40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2dd50 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
2dd60 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
2dd70 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
2dd80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
2dd90 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
2dda0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e  update hook.  An
2ddb0 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
2ddc0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2ddd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2dde0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
2ddf0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
2de00 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
2de10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2de20 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
2de30 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70  triggered the up
2de40 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f  date hook..** No
2de50 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
2de60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2de70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
2de80 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
2de90 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
2dea0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
2deb0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
2dec0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
2ded0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
2dee0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2def0 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c  update_hook(D,C,
2df00 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  P) function.** r
2df10 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67  eturns the P arg
2df20 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2df30 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20  revious call.** 
2df40 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2df50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2df60 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
2df70 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
2df80 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53  ll on D..**.** S
2df90 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
2dfa0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2dfb0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2dfc0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
2dfd0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ].** interfaces.
2dfe0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2dff0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
2e000 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
2e010 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
2e020 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
2e030 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
2e040 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
2e050 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
2e060 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
2e070 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
2e080 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20   Pager Cache.** 
2e090 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
2e0a0 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e  d cache}.**.** ^
2e0b0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
2e0c0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
2e0d0 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
2e0e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
2e0f0 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
2e100 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
2e110 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
2e120 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
2e130 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
2e140 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
2e150 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
2e160 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
2e170 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
2e180 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
2e190 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
2e1a0 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
2e1b0 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
2e1c0 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
2e1d0 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
2e1e0 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
2e1f0 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
2e200 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
2e210 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
2e220 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
2e230 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
2e240 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
2e250 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
2e260 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
2e270 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
2e280 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
2e290 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
2e2a0 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
2e2b0 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
2e2c0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2e2d0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
2e2e0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
2e2f0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
2e300 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2e310 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
2e320 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2e330 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
2e340 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
2e350 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
2e360 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
2e370 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
2e380 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
2e390 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
2e3a0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
2e3b0 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
2e3c0 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
2e3d0 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
2e3e0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
2e3f0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2e400 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
2e410 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
2e420 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
2e430 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
2e440 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
2e450 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
2e460 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
2e470 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
2e480 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
2e490 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
2e4a0 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
2e4b0 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
2e4c0 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  licitly..**.** S
2e4d0 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74  ee Also:  [SQLit
2e4e0 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d  e Shared-Cache M
2e4f0 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ode].*/.int sqli
2e500 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
2e510 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
2e520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
2e530 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
2e540 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
2e550 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2e560 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
2e570 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2e580 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
2e590 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
2e5a0 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
2e5b0 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
2e5c0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
2e5d0 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
2e5e0 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
2e5f0 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
2e600 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
2e610 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
2e620 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
2e630 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
2e640 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
2e650 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
2e660 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
2e670 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
2e680 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2e690 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
2e6a0 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
2e6b0 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
2e6c0 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
2e6d0 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
2e6e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  */.int sqlite3_r
2e6f0 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69 6e  elease_memory(in
2e700 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e710 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69  REF: Impose A Li
2e720 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65  mit On Heap Size
2e730 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e740 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
2e750 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2e760 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22 20  places a "soft" 
2e770 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65 20  limit.** on the 
2e780 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20 6d  amount of heap m
2e790 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20 62  emory that may b
2e7a0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53  e allocated by S
2e7b0 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61 6e  QLite..** ^If an
2e7c0 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63 61   internal alloca
2e7d0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
2e7e0 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78 63  d that would exc
2e7f0 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20  eed the.** soft 
2e800 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71 6c  heap limit, [sql
2e810 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
2e820 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ory()] is invoke
2e830 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72 65  d one or.** more
2e840 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20 75   times to free u
2e850 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65 66  p some space bef
2e860 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 69  ore the allocati
2e870 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
2e880 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d 69  .**.** ^The limi
2e890 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f 66  t is called "sof
2e8a0 74 22 20 62 65 63 61 75 73 65 20 69 66 20 5b 73  t" because if [s
2e8b0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2e8c0 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e 6e  emory()].** cann
2e8d0 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69 65  ot free sufficie
2e8e0 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72 65  nt memory to pre
2e8f0 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20 66  vent the limit f
2e900 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65 64  rom being exceed
2e910 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72  ed,.** the memor
2e920 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 61  y is allocated a
2e930 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63 75  nyway and the cu
2e940 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 20  rrent operation 
2e950 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  proceeds..**.** 
2e960 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20 7a  ^A negative or z
2e970 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e 20  ero value for N 
2e980 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72 65  means that there
2e990 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61 70   is no soft heap
2e9a0 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b 73   limit and.** [s
2e9b0 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
2e9c0 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f 6e  emory()] will on
2e9d0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2e9e0 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68 61  n memory is exha
2e9f0 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  usted..** ^The d
2ea00 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
2ea10 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
2ea20 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  imit is zero..**
2ea30 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61 6b  .** ^(SQLite mak
2ea40 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72 74  es a best effort
2ea50 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73 6f   to honor the so
2ea60 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a 2a  ft heap limit..*
2ea70 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f 66  * But if the sof
2ea80 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
2ea90 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c 20  not be honored, 
2eaa0 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a 2a  execution will.*
2eab0 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68 6f  * continue witho
2eac0 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74 69  ut error or noti
2ead0 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68 69  fication.)^  Thi
2eae0 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69 6d  s is why the lim
2eaf0 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 20  it is.** called 
2eb00 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e 20  a "soft" limit. 
2eb10 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79 20   It is advisory 
2eb20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  only..**.** Prio
2eb30 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
2eb40 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73 20  ion 3.5.0, this 
2eb50 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f 6e  routine only con
2eb60 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65 6d  strained the mem
2eb70 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 64  ory.** allocated
2eb80 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
2eb90 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20 74  ead - the same t
2eba0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20 74  hread in which t
2ebb0 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
2ebc0 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67 20  uns.  Beginning 
2ebd0 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
2ebe0 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20 73  ion 3.5.0, the s
2ebf0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
2ec00 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f 20  s.** applied to 
2ec10 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68 65  all threads. The
2ec20 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2ec30 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68 65   for the soft he
2ec40 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20 61  ap limit.** is a
2ec50 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f 6e  n upper bound on
2ec60 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f 72   the total memor
2ec70 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
2ec80 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49 6e   all threads. In
2ec90 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  .** version 3.5.
2eca0 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  0 there is no me
2ecb0 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d 69  chanism for limi
2ecc0 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75 73  ting the heap us
2ecd0 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69 76  age for.** indiv
2ece0 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a 2a  idual threads..*
2ecf0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  /.void sqlite3_s
2ed00 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
2ed10 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2ed20 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d 65  3REF: Extract Me
2ed30 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20 43  tadata About A C
2ed40 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c 65  olumn Of A Table
2ed50 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2ed60 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65 74  tine returns met
2ed70 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73 70  adata about a sp
2ed80 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f 66  ecific column of
2ed90 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 64   a specific.** d
2eda0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 63  atabase table ac
2edb0 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20 74  cessible using t
2edc0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2edd0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
2ede0 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
2edf0 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e 20   first function 
2ee00 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2ee10 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 69  ^The column is i
2ee20 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2ee30 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20 61   second, third a
2ee40 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
2ee50 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73 20  ters to.** this 
2ee60 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20 73  function. ^The s
2ee70 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2ee80 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e 61  is either the na
2ee90 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2eea0 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61 69  se.** (i.e. "mai
2eeb0 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20 61  n", "temp", or a
2eec0 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  n attached datab
2eed0 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ase) containing 
2eee0 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  the specified.**
2eef0 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20   table or NULL. 
2ef00 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c 20  ^If it is NULL, 
2ef10 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68 65  then all attache
2ef20 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65 20  d databases are 
2ef30 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72 20  searched.** for 
2ef40 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67 20  the table using 
2ef50 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
2ef60 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20 64  hm used by the d
2ef70 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 74  atabase engine t
2ef80 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e 71  o.** resolve unq
2ef90 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20 72  ualified table r
2efa0 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a  eferences..**.**
2efb0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
2efc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2efd0 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
2efe0 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c 65  on are the table
2eff0 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e   and column.** n
2f000 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69 72  ame of the desir
2f010 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70 65  ed column, respe
2f020 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65 72  ctively. Neither
2f030 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d 65   of these parame
2f040 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  ters.** may be N
2f050 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61  ULL..**.** ^Meta
2f060 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65 64  data is returned
2f070 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20 74   by writing to t
2f080 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74 69  he memory locati
2f090 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74 68  ons passed as th
2f0a0 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75 62  e 5th.** and sub
2f0b0 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74 65  sequent paramete
2f0c0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
2f0d0 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68 65  ion. ^Any of the
2f0e0 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61 79  se arguments may
2f0f0 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20   be.** NULL, in 
2f100 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 63  which case the c
2f110 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c 65  orresponding ele
2f120 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74 61  ment of metadata
2f130 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a   is omitted..**.
2f140 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74 65  ** ^(<blockquote
2f150 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2f160 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2f170 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c 74  th> Parameter <t
2f180 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79 70  h> Output<br>Typ
2f190 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70 74  e <th>  Descript
2f1a0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74  ion.**.** <tr><t
2f1b0 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 5th <td> cons
2f1c0 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61 74  t char* <td> Dat
2f1d0 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74  a type.** <tr><t
2f1e0 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e 73  d> 6th <td> cons
2f1f0 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61 6d  t char* <td> Nam
2f200 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f 6c  e of default col
2f210 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 0a  lation sequence.
2f220 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68 20  ** <tr><td> 7th 
2f230 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
2f240 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
2f250 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20 4e  lumn has a NOT N
2f260 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  ULL constraint.*
2f270 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20 3c  * <tr><td> 8th <
2f280 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2f290 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2f2a0 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20 74  umn is part of t
2f2b0 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a 2a  he PRIMARY KEY.*
2f2c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20 3c  * <tr><td> 9th <
2f2d0 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20 20  td> int         
2f2e0 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f 6c  <td> True if col
2f2f0 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43 52  umn is [AUTOINCR
2f300 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c  EMENT].** </tabl
2f310 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
2f320 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
2f330 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64 20   memory pointed 
2f340 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61 63  to by the charac
2f350 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ter pointers ret
2f360 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a  urned for the.**
2f370 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79 70   declaration typ
2f380 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  e and collation 
2f390 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c 69  sequence is vali
2f3a0 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68 65  d only until the
2f3b0 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f   next.** call to
2f3c0 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49 20   any SQLite API 
2f3d0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2f3e0 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
2f3f0 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75 61  d table is actua
2f400 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20 5b  lly a view, an [
2f410 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2f420 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2f430 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65 64  If the specified
2f440 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77 69   column is "rowi
2f450 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f 72  d", "oid" or "_r
2f460 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a  owid_" and an.**
2f470 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
2f480 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68 61  Y KEY] column ha
2f490 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74 6c  s been explicitl
2f4a0 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65 6e  y declared, then
2f4b0 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2f4c0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2f4d0 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69 63  t for the explic
2f4e0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
2f4f0 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72 65  lumn. ^(If there
2f500 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63   is no.** explic
2f510 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b 49  itly declared [I
2f520 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b  NTEGER PRIMARY K
2f530 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e  EY] column, then
2f540 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20 70   the output.** p
2f550 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73 65  arameters are se
2f560 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
2f570 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  .** <pre>.**    
2f580 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e 54   data type: "INT
2f590 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f 6c  EGER".**     col
2f5a0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 3a  lation sequence:
2f5b0 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20 20   "BINARY".**    
2f5c0 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20   not null: 0.** 
2f5d0 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79 3a      primary key:
2f5e0 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20 69   1.**     auto i
2f5f0 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c  ncrement: 0.** <
2f600 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  /pre>)^.**.** ^(
2f610 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61  This function ma
2f620 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d 6f  y load one or mo
2f630 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d 20  re schemas from 
2f640 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e 20  database files. 
2f650 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f  If an.** error o
2f660 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 69  ccurs during thi
2f670 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66  s process, or if
2f680 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 74   the requested t
2f690 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a  able or column.*
2f6a0 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75 6e  * cannot be foun
2f6b0 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  d, an [error cod
2f6c0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  e] is returned a
2f6d0 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  nd an error mess
2f6e0 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20 74  age left.** in t
2f6f0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2f700 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65 20  nection] (to be 
2f710 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67 20  retrieved using 
2f720 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2f730 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ).)^.**.** ^This
2f740 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76 61   API is only ava
2f750 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2f760 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2f770 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2f780 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2f790 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2f7a0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2f7b0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2f  mbol defined..*/
2f7c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62  .int sqlite3_tab
2f7d0 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61  le_column_metada
2f7e0 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ta(.  sqlite3 *d
2f7f0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
2f800 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20    /* Connection 
2f810 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2f820 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c  t char *zDbName,
2f830 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2f840 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c  ase name or NULL
2f850 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2f860 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20   *zTableName,   
2f870 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20    /* Table name 
2f880 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2f890 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20  *zColumnName,   
2f8a0 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20   /* Column name 
2f8b0 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
2f8c0 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20  **pzDataType,   
2f8d0 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c   /* OUTPUT: Decl
2f8e0 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20 2a  ared data type *
2f8f0 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a  /.  char const *
2f900 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20  *pzCollSeq,     
2f910 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61  /* OUTPUT: Colla
2f920 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61  tion sequence na
2f930 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f  me */.  int *pNo
2f940 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20  tNull,          
2f950 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
2f960 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20  rue if NOT NULL 
2f970 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74  constraint exist
2f980 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69  s */.  int *pPri
2f990 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20  maryKey,        
2f9a0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
2f9b0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72  ue if column par
2f9c0 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74  t of PK */.  int
2f9d0 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20   *pAutoinc      
2f9e0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50           /* OUTP
2f9f0 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75  UT: True if colu
2fa00 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65  mn is auto-incre
2fa10 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  ment */.);../*.*
2fa20 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
2fa30 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a   An Extension.**
2fa40 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
2fa50 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c  ace loads an SQL
2fa60 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69  ite extension li
2fa70 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e  brary from the n
2fa80 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  amed file..**.**
2fa90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
2faa0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2fab0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2fac0 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20  s to load an.** 
2fad0 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e  SQLite extension
2fae0 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e   library contain
2faf0 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a  ed in the file z
2fb00 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  File..**.** ^The
2fb10 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20   entry point is 
2fb20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63  zProc..** ^zProc
2fb30 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68   may be 0, in wh
2fb40 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d  ich case the nam
2fb50 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70  e of the entry p
2fb60 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73  oint.** defaults
2fb70 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74   to "sqlite3_ext
2fb80 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a  ension_init"..**
2fb90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f   ^The sqlite3_lo
2fba0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69  ad_extension() i
2fbb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2fbc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
2fbd0 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b  on success and [
2fbe0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
2fbf0 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20   something goes 
2fc00 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e  wrong..** ^If an
2fc10 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e   error occurs an
2fc20 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f  d pzErrMsg is no
2fc30 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a  t 0, then the.**
2fc40 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
2fc50 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65  xtension()] inte
2fc60 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65  rface shall atte
2fc70 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a  mpt to.** fill *
2fc80 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65 72  pzErrMsg with er
2fc90 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
2fca0 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72   stored in memor
2fcb0 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72  y.** obtained fr
2fcc0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2fcd0 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69  oc()]. The calli
2fce0 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  ng function.** s
2fcf0 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73 20  hould free this 
2fd00 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e  memory by callin
2fd10 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  g [sqlite3_free(
2fd20 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e  )]..**.** ^Exten
2fd30 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73  sion loading mus
2fd40 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69  t be enabled usi
2fd50 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  ng.** [sqlite3_e
2fd60 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
2fd70 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f  sion()] prior to
2fd80 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50   calling this AP
2fd90 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  I,.** otherwise 
2fda0 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  an error will be
2fdb0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
2fdc0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c   See also the [l
2fdd0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
2fde0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
2fdf0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 6f  /.int sqlite3_lo
2fe00 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20 20  ad_extension(.  
2fe10 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2fe20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74 68        /* Load th
2fe30 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74 6f  e extension into
2fe40 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20 63   this database c
2fe50 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20 63  onnection */.  c
2fe60 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
2fe70 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20  ,    /* Name of 
2fe80 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72 61  the shared libra
2fe90 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65 78  ry containing ex
2fea0 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e  tension */.  con
2feb0 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c 20  st char *zProc, 
2fec0 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69 6e     /* Entry poin
2fed0 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f 6d  t.  Derived from
2fee0 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a 20   zFile if 0 */. 
2fef0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67   char **pzErrMsg
2ff00 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65 72         /* Put er
2ff10 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72 65  ror message here
2ff20 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b 0a   if not 0 */.);.
2ff30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ff40 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
2ff50 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61  le Extension Loa
2ff60 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20 61  ding.**.** ^So a
2ff70 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73 65  s not to open se
2ff80 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e 20  curity holes in 
2ff90 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69 6f  older applicatio
2ffa0 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 75  ns that are.** u
2ffb0 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65 61  nprepared to dea
2ffc0 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f 6e  l with extension
2ffd0 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61 73   loading, and as
2ffe0 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73 61   a means of disa
2fff0 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73 69  bling.** extensi
30000 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c 65  on loading while
30010 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65 72   evaluating user
30020 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74 68  -entered SQL, th
30030 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49 0a  e following API.
30040 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  ** is provided t
30050 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c 69  o turn the [sqli
30060 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
30070 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d 20  on()] mechanism 
30080 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a 2a  on and off..**.*
30090 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  * ^Extension loa
300a0 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20 64  ding is off by d
300b0 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63 6b  efault. See tick
300c0 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43 61  et #1863..** ^Ca
300d0 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  ll the sqlite3_e
300e0 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e  nable_load_exten
300f0 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20 77  sion() routine w
30100 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a 20  ith onoff==1.** 
30110 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69 6f  to turn extensio
30120 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e 64  n loading on and
30130 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f 6e   call it with on
30140 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a 2a  off==0 to turn.*
30150 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61 67  * it back off ag
30160 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ain..*/.int sqli
30170 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f  te3_enable_load_
30180 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65  extension(sqlite
30190 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66  3 *db, int onoff
301a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
301b0 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c  EF: Automaticall
301c0 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e 73  y Load An Extens
301d0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ions.**.** ^This
301e0 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76 6f   API can be invo
301f0 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20 73  ked at program s
30200 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72 20  tartup in order 
30210 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20 6f  to register.** o
30220 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74 69  ne or more stati
30230 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78 74  cally linked ext
30240 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69 6c  ensions that wil
30250 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a 2a  l be available.*
30260 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64 61  * to all new [da
30270 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30280 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ns]..**.** ^(Thi
30290 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
302a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
302b0 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74 72  e extension entr
302c0 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61 6e  y point.** in an
302d0 20 61 72 72 61 79 20 74 68 61 74 20 69 73 20 6f   array that is o
302e0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
302f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
30300 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a    That memory.**
30310 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   is deallocated 
30320 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  by [sqlite3_rese
30330 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
30340 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
30350 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  is function regi
30360 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73 69  sters an extensi
30370 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 74  on entry point t
30380 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  hat is.** automa
30390 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64 20  tically invoked 
303a0 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20 5b  whenever a new [
303b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
303c0 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e 65  ion].** is opene
303d0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
303e0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
303f0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
30400 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
30410 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75 70  n_v2()]..** ^Dup
30420 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f 6e  licate extension
30430 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20 73  s are detected s
30440 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 72  o calling this r
30450 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69 70  outine.** multip
30460 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  le times with th
30470 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f 6e  e same extension
30480 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a 2a   is harmless..**
30490 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78 74 65   ^Automatic exte
304a0 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63 72  nsions apply acr
304b0 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73 2e  oss all threads.
304c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
304d0 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 76  auto_extension(v
304e0 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69 6e  oid (*xEntryPoin
304f0 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a 2a  t)(void));../*.*
30500 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
30510 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74 65  t Automatic Exte
30520 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
30530 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74  .** ^(This funct
30540 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c 6c  ion disables all
30550 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67 69   previously regi
30560 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69 63  stered automatic
30570 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e 20  .** extensions. 
30580 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  It undoes the ef
30590 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69 6f  fect of all prio
305a0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 75  r.** [sqlite3_au
305b0 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  to_extension()] 
305c0 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  calls.)^.**.** ^
305d0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64 69  This function di
305e0 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69 63  sables automatic
305f0 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20 61   extensions in a
30600 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a 76  ll threads..*/.v
30610 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 65  oid sqlite3_rese
30620 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
30630 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  (void);../*.** T
30640 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
30650 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
30660 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20 63  e mechanism is c
30670 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65  urrently conside
30680 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70  red.** to be exp
30690 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20  erimental.  The 
306a0 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74 20  interface might 
306b0 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70  change in incomp
306c0 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20  atible ways..** 
306d0 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72 6f  If this is a pro
306e0 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f  blem for you, do
306f0 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e 74   not use the int
30700 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20 74  erface at this t
30710 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ime..**.** When 
30720 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c  the virtual-tabl
30730 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61 62  e mechanism stab
30740 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20  ilizes, we will 
30750 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69  declare the.** i
30760 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c 20  nterface fixed, 
30770 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65 66  support it indef
30780 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d  initely, and rem
30790 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74  ove this comment
307a0 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72 75  ..*/../*.** Stru
307b0 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20 74  ctures used by t
307c0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
307d0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74 79   interface.*/.ty
307e0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
307f0 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74 65  ite3_vtab sqlite
30800 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66 20  3_vtab;.typedef 
30810 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
30820 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74 65  ndex_info sqlite
30830 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74 79  3_index_info;.ty
30840 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
30850 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
30860 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
30870 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73 74  rsor;.typedef st
30880 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
30890 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  ule sqlite3_modu
308a0 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  le;../*.** CAPI3
308b0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
308c0 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  le Object.** KEY
308d0 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 6d  WORDS: sqlite3_m
308e0 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20 74  odule {virtual t
308f0 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a 0a  able module}.**.
30900 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75 72  ** This structur
30910 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61 6c  e, sometimes cal
30920 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 61 6c  led a a "virtual
30930 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c 20   table module", 
30940 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65 20  .** defines the 
30950 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
30960 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  f a [virtual tab
30970 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73 20  les].  .** This 
30980 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69 73  structure consis
30990 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65 74  ts mostly of met
309a0 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
309b0 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76 69  ule..**.** ^A vi
309c0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
309d0 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62 79  le is created by
309e0 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70 65   filling in a pe
309f0 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73 74  rsistent.** inst
30a00 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74 72  ance of this str
30a10 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73 69  ucture and passi
30a20 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ng a pointer to 
30a30 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a 2a  that instance.**
30a40 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
30a50 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f 72  ate_module()] or
30a60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
30a70 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a 2a  _module_v2()]..*
30a80 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72 61 74  * ^The registrat
30a90 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c 69  ion remains vali
30aa0 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72 65  d until it is re
30ab0 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 66 66  placed by a diff
30ac0 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65 20  erent.** module 
30ad0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64 61  or until the [da
30ae0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30af0 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65 20  n] closes.  The 
30b00 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  content.** of th
30b10 69 73 20 73 74 72 75 63 74 75 72 65 20 6d 75 73  is structure mus
30b20 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68 69  t not change whi
30b30 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 74 65  le it is registe
30b40 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79 20  red with.** any 
30b50 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30b60 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ion..*/.struct s
30b70 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 0a  qlite3_module {.
30b80 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
30b90 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65 29    int (*xCreate)
30ba0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20  (sqlite3*, void 
30bb0 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20  *pAux,.         
30bc0 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20        int argc, 
30bd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73  const char *cons
30be0 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20  t*argv,.        
30bf0 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76         sqlite3_v
30c00 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68  tab **ppVTab, ch
30c10 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ar**);.  int (*x
30c20 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  Connect)(sqlite3
30c30 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20  *, void *pAux,. 
30c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
30c50 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68  t argc, const ch
30c60 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a  ar *const*argv,.
30c70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73                 s
30c80 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70  qlite3_vtab **pp
30c90 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20  VTab, char**);. 
30ca0 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64 65   int (*xBestInde
30cb0 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  x)(sqlite3_vtab 
30cc0 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f  *pVTab, sqlite3_
30cd0 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20 20  index_info*);.  
30ce0 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65 63  int (*xDisconnec
30cf0 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
30d00 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
30d10 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69 74  *xDestroy)(sqlit
30d20 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b  e3_vtab *pVTab);
30d30 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
30d40 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
30d50 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74 61  Tab, sqlite3_vta
30d60 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75 72  b_cursor **ppCur
30d70 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sor);.  int (*xC
30d80 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 74  lose)(sqlite3_vt
30d90 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69  ab_cursor*);.  i
30da0 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73 71  nt (*xFilter)(sq
30db0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
30dc0 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c 20  r*, int idxNum, 
30dd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78 53  const char *idxS
30de0 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  tr,.            
30df0 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73 71      int argc, sq
30e00 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61 72  lite3_value **ar
30e10 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e 65  gv);.  int (*xNe
30e20 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  xt)(sqlite3_vtab
30e30 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74  _cursor*);.  int
30e40 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65 33   (*xEof)(sqlite3
30e50 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
30e60 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e 29    int (*xColumn)
30e70 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75  (sqlite3_vtab_cu
30e80 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 63  rsor*, sqlite3_c
30e90 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 20  ontext*, int);. 
30ea0 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28 73   int (*xRowid)(s
30eb0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30ec0 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  or*, sqlite3_int
30ed0 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20 69  64 *pRowid);.  i
30ee0 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73 71  nt (*xUpdate)(sq
30ef0 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69 6e  lite3_vtab *, in
30f00 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  t, sqlite3_value
30f10 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74   **, sqlite3_int
30f20 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  64 *);.  int (*x
30f30 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f 76  Begin)(sqlite3_v
30f40 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69  tab *pVTab);.  i
30f50 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
30f60 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
30f70 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d 69  ;.  int (*xCommi
30f80 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  t)(sqlite3_vtab 
30f90 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28  *pVTab);.  int (
30fa0 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c 69  *xRollback)(sqli
30fb0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
30fc0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64 46  ;.  int (*xFindF
30fd0 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65 33  unction)(sqlite3
30fe0 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69 6e  _vtab *pVtab, in
30ff0 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63 68  t nArg, const ch
31000 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20 20  ar *zName,.     
31010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31020 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e 63    void (**pxFunc
31030 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31040 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
31050 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20 20  alue**),.       
31060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31070 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a 20  void **ppArg);. 
31080 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29 28   int (*xRename)(
31090 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
310a0 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  tab, const char 
310b0 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a  *zNew);.};../*.*
310c0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
310d0 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78 69  ual Table Indexi
310e0 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ng Information.*
310f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
31100 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a 2a  te3_index_info.*
31110 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31120 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72 75  _index_info stru
31130 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73 75  cture and its su
31140 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20 75  bstructures is u
31150 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69  sed to.** pass i
31160 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20  nformation into 
31170 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65 20  and receive the 
31180 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b  reply from the [
31190 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d  xBestIndex].** m
311a0 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72 74  ethod of a [virt
311b0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
311c0 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20 75  ].  The fields u
311d0 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20  nder **Inputs** 
311e0 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  are the.** input
311f0 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78 20  s to xBestIndex 
31200 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c  and are read-onl
31210 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20 69  y.  xBestIndex i
31220 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72 65  nserts its.** re
31230 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20 2a  sults into the *
31240 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c 64  *Outputs** field
31250 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61  s..**.** ^(The a
31260 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
31270 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 52 45  ay records WHERE
31280 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69   clause constrai
31290 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a  nts of the form:
312a0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c 75  .**.** <pre>colu
312b0 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65 3e  mn OP expr</pre>
312c0 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50 20  .**.** where OP 
312d0 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74 3b  is =, &lt;, &lt;
312e0 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74 3b  =, &gt;, or &gt;
312f0 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61 72 74  =.)^  ^(The part
31300 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72 20  icular operator 
31310 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e 20  is.** stored in 
31320 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f 70  aConstraint[].op
31330 2e 29 5e 20 20 5e 28 54 68 65 20 69 6e 64 65 78  .)^  ^(The index
31340 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
31350 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61  s stored in.** a
31360 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f  Constraint[].iCo
31370 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73  lumn.)^  ^(aCons
31380 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
31390 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
313a0 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
313b0 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
313c0 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
313d0 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
313e0 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
313f0 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
31400 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a  if it cannot.)^.
31410 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d  **.** ^The optim
31420 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
31430 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
31440 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
31450 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
31460 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
31470 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
31480 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
31490 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
314a0 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
314b0 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
314c0 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
314d0 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
314e0 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
314f0 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69  * ^The aConstrai
31500 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
31510 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
31520 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20  ause terms that 
31530 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20  are.** relevant 
31540 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
31550 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
31560 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
31570 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f  *.** ^Informatio
31580 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
31590 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
315a0 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
315b0 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65  y[]..** ^Each te
315c0 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72  rm of aOrderBy r
315d0 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20  ecords a column 
315e0 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  of the ORDER BY 
315f0 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  clause..**.** Th
31600 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d  e [xBestIndex] m
31610 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20  ethod must fill 
31620 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
31630 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  [] with informat
31640 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61  ion.** about wha
31650 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
31660 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e  pass to xFilter.
31670 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e    ^If argvIndex>
31680 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69  0 then.** the ri
31690 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  ght-hand side of
316a0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
316b0 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ng aConstraint[]
316c0 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a   is evaluated.**
316d0 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65   and becomes the
316e0 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e   argvIndex-th en
316f0 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28  try in argv.  ^(
31700 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
31710 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
31720 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
31730 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
31740 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
31750 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
31760 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
31770 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
31780 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
31790 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  Lite.)^.**.** ^T
317a0 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64  he idxNum and id
317b0 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20  xPtr values are 
317c0 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73  recorded and pas
317d0 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  sed into the.** 
317e0 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64  [xFilter] method
317f0 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66  ..** ^[sqlite3_f
31800 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74  ree()] is used t
31810 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66  o free idxPtr if
31820 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
31830 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
31840 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
31850 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73  ^The orderByCons
31860 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20  umed means that 
31870 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69  output from [xFi
31880 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69  lter]/[xNext] wi
31890 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
318a0 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
318b0 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
318c0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
318d0 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
318e0 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
318f0 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
31900 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69  .**.** ^The esti
31910 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20  matedCost value 
31920 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  is an estimate o
31930 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f  f the cost of do
31940 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69  ing the.** parti
31950 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41  cular lookup.  A
31960 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20   full scan of a 
31970 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74  table with N ent
31980 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
31990 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e  .** a cost of N.
319a0 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63    A binary searc
319b0 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20  h of a table of 
319c0 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
319d0 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20   have a.** cost 
319e0 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
319f0 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75   log(N)..*/.stru
31a00 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
31a10 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
31a20 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f  uts */.  int nCo
31a30 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
31a40 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
31a50 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
31a60 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72  straint */.  str
31a70 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
31a80 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20  x_constraint {. 
31a90 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
31aa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
31ab0 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d   Column on left-
31ac0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e  hand side of con
31ad0 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20  straint */.     
31ae0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70  unsigned char op
31af0 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e  ;         /* Con
31b00 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72  straint operator
31b10 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
31b20 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20  d char usable;  
31b30 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68     /* True if th
31b40 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  is constraint is
31b50 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20   usable */.     
31b60 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b  int iTermOffset;
31b70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
31b80 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78  d internally - x
31b90 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64  BestIndex should
31ba0 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a   ignore */.  } *
31bb0 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
31bc0 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65          /* Table
31bd0 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65   of WHERE clause
31be0 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a   constraints */.
31bf0 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20    int nOrderBy; 
31c00 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
31c10 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  Number of terms 
31c20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  in the ORDER BY 
31c30 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75  clause */.  stru
31c40 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
31c50 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
31c60 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
31c70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
31c80 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  umn number */.  
31c90 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
31ca0 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20   desc;       /* 
31cb0 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20  True for DESC.  
31cc0 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a  False for ASC. *
31cd0 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b  /.  } *aOrderBy;
31ce0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
31cf0 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
31d00 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75  lause */.  /* Ou
31d10 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63  tputs */.  struc
31d20 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
31d30 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65  constraint_usage
31d40 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49   {.    int argvI
31d50 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20  ndex;           
31d60 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72  /* if >0, constr
31d70 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
31d80 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
31d90 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  */.    unsigned 
31da0 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20  char omit;      
31db0 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61  /* Do not code a
31dc0 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63   test for this c
31dd0 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d  onstraint */.  }
31de0 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61   *aConstraintUsa
31df0 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
31e00 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
31e10 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
31e20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
31e30 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
31e40 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
31e50 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
31e60 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
31e70 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
31e80 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
31e90 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
31ea0 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
31eb0 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
31ec0 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
31ed0 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
31ee0 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
31ef0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
31f00 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
31f10 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
31f20 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
31f30 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
31f40 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
31f50 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
31f60 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .};.#define SQLI
31f70 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
31f80 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65 66  INT_EQ    2.#def
31f90 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
31fa0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20 20  _CONSTRAINT_GT  
31fb0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
31fc0 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41  TE_INDEX_CONSTRA
31fd0 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65 66  INT_LE    8.#def
31fe0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45 58  ine SQLITE_INDEX
31ff0 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20 20  _CONSTRAINT_LT  
32000 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c    16.#define SQL
32010 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
32020 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23 64  AINT_GE    32.#d
32030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
32040 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d 41  EX_CONSTRAINT_MA
32050 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43 41  TCH 64../*.** CA
32060 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
32070 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65   A Virtual Table
32080 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   Implementation.
32090 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
320a0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
320b0 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65 77  o register a new
320c0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
320d0 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a 2a  module] name..**
320e0 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20 6d   ^Module names m
320f0 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72 65  ust be registere
32100 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65 61  d before.** crea
32110 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72 74  ting a new [virt
32120 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e 67  ual table] using
32130 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64 20   the module and 
32140 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a 2a  before using a.*
32150 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b 76  * preexisting [v
32160 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66 6f  irtual table] fo
32170 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  r the module..**
32180 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65 20  .** ^The module 
32190 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74 65 72  name is register
321a0 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62  ed on the [datab
321b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
321c0 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
321d0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
321e0 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65 20  ter.  ^The name 
321f0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 73  of the module is
32200 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a 2a   given by the .*
32210 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
32220 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  er.  ^The third 
32230 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
32240 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ointer to.** the
32250 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32260 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
32270 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20  table module].  
32280 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a 20   ^The fourth.** 
32290 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
322a0 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e 74  arbitrary client
322b0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
322c0 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  at is passed thr
322d0 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  ough.** into the
322e0 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b   [xCreate] and [
322f0 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64  xConnect] method
32300 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61 6c  s of the virtual
32310 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a 2a   table module.**
32320 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72 74   when a new virt
32330 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65 20  ual table is be 
32340 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f 72  being created or
32350 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e 0a   reinitialized..
32360 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32370 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
32380 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
32390 68 61 73 20 61 20 66 69 66 74 68 20 70 61 72 61  has a fifth para
323a0 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
323b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
323c0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
323d0 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61 2e  the pClientData.
323e0 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a    ^SQLite will.*
323f0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  * invoke the des
32400 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
32410 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   (if it is not N
32420 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74 65  ULL) when SQLite
32430 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65  .** no longer ne
32440 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74 44  eds the pClientD
32450 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ata pointer.  ^T
32460 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
32470 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e  e_module().** in
32480 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76  terface is equiv
32490 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  alent to sqlite3
324a0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
324b0 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a  2() with a NULL.
324c0 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a  ** destructor..*
324d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  /.int sqlite3_cr
324e0 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73  eate_module(.  s
324f0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
32500 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
32510 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
32520 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
32530 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
32540 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
32550 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
32560 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
32570 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
32580 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
32590 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
325a0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
325b0 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20   *pClientData   
325c0 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
325d0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
325e0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b  e/xConnect */.);
325f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
32600 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20  ate_module_v2(. 
32610 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
32620 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
32630 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  QLite connection
32640 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64   to register mod
32650 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f  ule with */.  co
32660 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
32670 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65           /* Name
32680 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a   of the module *
32690 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  /.  const sqlite
326a0 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f  3_module *p,   /
326b0 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  * Methods for th
326c0 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f  e module */.  vo
326d0 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c  id *pClientData,
326e0 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65           /* Clie
326f0 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65  nt data for xCre
32700 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a  ate/xConnect */.
32710 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
32720 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20  )(void*)     /* 
32730 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f  Module destructo
32740 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b  r function */.);
32750 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32760 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20  : Virtual Table 
32770 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a  Instance Object.
32780 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
32790 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20  ite3_vtab.**.** 
327a0 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74  Every [virtual t
327b0 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70  able module] imp
327c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73  lementation uses
327d0 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f   a subclass.** o
327e0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f  f this object to
327f0 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74   describe a part
32800 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a  icular instance.
32810 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  ** of the [virtu
32820 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68  al table].  Each
32830 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a   subclass will.*
32840 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f  * be tailored to
32850 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
32860 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  eds of the modul
32870 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32880 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65  ..** The purpose
32890 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c   of this supercl
328a0 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65  ass is to define
328b0 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20   certain fields 
328c0 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d  that are.** comm
328d0 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65  on to all module
328e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
328f0 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c  ..**.** ^Virtual
32900 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20   tables methods 
32910 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72  can set an error
32920 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69   message by assi
32930 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e  gning a.** strin
32940 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
32950 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
32960 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ()] to zErrMsg. 
32970 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75   The method shou
32980 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20  ld.** take care 
32990 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73  that any prior s
329a0 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62  tring is freed b
329b0 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
329c0 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
329d0 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69  prior to assigni
329e0 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20  ng a new string 
329f0 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66  to zErrMsg.  ^Af
32a00 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
32a10 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69  ssage.** is deli
32a20 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65 20  vered up to the 
32a30 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69  client applicati
32a40 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77  on, the string w
32a50 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
32a60 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79  ally.** freed by
32a70 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
32a80 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20  and the zErrMsg 
32a90 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65  field will be ze
32aa0 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  roed..*/.struct 
32ab0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20  sqlite3_vtab {. 
32ac0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
32ad0 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20  odule *pModule; 
32ae0 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66   /* The module f
32af0 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  or this virtual 
32b00 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e  table */.  int n
32b10 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20 20  Ref;            
32b20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f             /* NO
32b30 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a   LONGER USED */.
32b40 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b    char *zErrMsg;
32b50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32b60 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61    /* Error messa
32b70 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ge from sqlite3_
32b80 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f  mprintf() */.  /
32b90 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20  * Virtual table 
32ba0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
32bb0 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61  will typically a
32bc0 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  dd additional fi
32bd0 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  elds */.};../*.*
32be0 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
32bf0 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72  ual Table Cursor
32c00 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
32c10 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61  RDS: sqlite3_vta
32c20 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61  b_cursor {virtua
32c30 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a  l table cursor}.
32c40 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72  **.** Every [vir
32c50 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
32c60 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  e] implementatio
32c70 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61 73  n uses a subclas
32c80 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  s of the.** foll
32c90 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65 20  owing structure 
32ca0 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72 73  to describe curs
32cb0 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69  ors that point i
32cc0 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74  nto the.** [virt
32cd0 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61  ual table] and a
32ce0 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f  re used.** to lo
32cf0 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 76  op through the v
32d00 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43  irtual table.  C
32d10 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61 74  ursors are creat
32d20 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
32d30 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
32d40 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d  xOpen | xOpen] m
32d50 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64  ethod of the mod
32d60 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73 74  ule and are dest
32d70 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  royed.** by the 
32d80 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e  [sqlite3_module.
32d90 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d  xClose | xClose]
32da0 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72   method.  Cursor
32db0 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79  s are used.** by
32dc0 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20   the [xFilter], 
32dd0 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c  [xNext], [xEof],
32de0 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20   [xColumn], and 
32df0 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73  [xRowid] methods
32e00 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  .** of the modul
32e10 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20  e.  Each module 
32e20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
32e30 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68  ill define.** th
32e40 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63  e content of a c
32e50 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65 20  ursor structure 
32e60 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20  to suit its own 
32e70 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  needs..**.** Thi
32e80 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78 69  s superclass exi
32e90 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  sts in order to 
32ea0 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66  define fields of
32eb0 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61 74   the cursor that
32ec0 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74  .** are common t
32ed0 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61  o all implementa
32ee0 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74  tions..*/.struct
32ef0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75   sqlite3_vtab_cu
32f00 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33  rsor {.  sqlite3
32f10 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20  _vtab *pVtab;   
32f20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61     /* Virtual ta
32f30 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72 73  ble of this curs
32f40 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75  or */.  /* Virtu
32f50 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  al table impleme
32f60 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79  ntations will ty
32f70 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69  pically add addi
32f80 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f  tional fields */
32f90 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
32fa0 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65  REF: Declare The
32fb0 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72   Schema Of A Vir
32fc0 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a  tual Table.**.**
32fd0 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20   ^The [xCreate] 
32fe0 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d  and [xConnect] m
32ff0 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b  ethods of a.** [
33000 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
33010 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20  dule] call this 
33020 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
33030 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d  declare the form
33040 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e  at (the names an
33050 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20 74  d datatypes of t
33060 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a  he columns) of.*
33070 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  * the virtual ta
33080 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d  bles they implem
33090 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ent..*/.int sqli
330a0 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62  te3_declare_vtab
330b0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
330c0 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f   char *zSQL);../
330d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
330e0 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69  verload A Functi
330f0 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c  on For A Virtual
33100 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56   Table.**.** ^(V
33110 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61  irtual tables ca
33120 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e  n provide altern
33130 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ative implementa
33140 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f  tions of functio
33150 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ns.** using the 
33160 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20  [xFindFunction] 
33170 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76  method of the [v
33180 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
33190 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67  ule].  .** But g
331a0 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f  lobal versions o
331b0 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e  f those function
331c0 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20  s.** must exist 
331d0 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f  in order to be o
331e0 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a  verloaded.)^.**.
331f0 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61  ** ^(This API ma
33200 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61  kes sure a globa
33210 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66  l version of a f
33220 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70  unction with a p
33230 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d  articular.** nam
33240 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20  e and number of 
33250 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74  parameters exist
33260 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66  s.  If no such f
33270 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a  unction exists.*
33280 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50  * before this AP
33290 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e  I is called, a n
332a0 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  ew function is c
332b0 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20  reated.)^  ^The 
332c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
332d0 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e  * of the new fun
332e0 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75  ction always cau
332f0 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  ses an exception
33300 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20   to be thrown.  
33310 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75  So.** the new fu
33320 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f  nction is not go
33330 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20  od for anything 
33340 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20  by itself.  Its 
33350 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20  only.** purpose 
33360 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65  is to be a place
33370 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20  holder function 
33380 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
33390 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b  loaded.** by a [
333a0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a  virtual table]..
333b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
333c0 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e  verload_function
333d0 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74  (sqlite3*, const
333e0 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65   char *zFuncName
333f0 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a  , int nArg);../*
33400 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63  .** The interfac
33410 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c  e to the virtual
33420 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d  -table mechanism
33430 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28   defined above (
33440 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20  back up.** to a 
33450 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62  comment remarkab
33460 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68  ly similar to th
33470 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65  is one) is curre
33480 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a  ntly considered.
33490 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d  ** to be experim
334a0 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65  ental.  The inte
334b0 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e  rface might chan
334c0 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62  ge in incompatib
334d0 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74  le ways..** If t
334e0 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d  his is a problem
334f0 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74   for you, do not
33500 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66 61   use the interfa
33510 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e  ce at this time.
33520 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
33530 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65  virtual-table me
33540 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a  chanism stabiliz
33550 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c  es, we will decl
33560 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72  are the.** inter
33570 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70 70  face fixed, supp
33580 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74  ort it indefinit
33590 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20  ely, and remove 
335a0 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f  this comment..*/
335b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
335c0 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e  : A Handle To An
335d0 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45   Open BLOB.** KE
335e0 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61  YWORDS: {BLOB ha
335f0 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64  ndle} {BLOB hand
33600 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  les}.**.** An in
33610 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
33620 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
33630 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e   an open BLOB on
33640 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
33650 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
33660 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
33670 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66  I/O] can be perf
33680 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63  ormed..** ^Objec
33690 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65 20  ts of this type 
336a0 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20 5b  are created by [
336b0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
336c0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74  n()].** and dest
336d0 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
336e0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e  3_blob_close()].
336f0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
33700 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
33710 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
33720 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66  _write()] interf
33730 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75  aces.** can be u
33740 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77  sed to read or w
33750 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65  rite small subse
33760 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c  ctions of the BL
33770 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  OB..** ^The [sql
33780 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
33790 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
337a0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
337b0 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74   the BLOB in byt
337c0 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  es..*/.typedef s
337d0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c  truct sqlite3_bl
337e0 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b  ob sqlite3_blob;
337f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33800 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f  : Open A BLOB Fo
33810 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f  r Incremental I/
33820 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  O.**.** ^(This i
33830 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20  nterfaces opens 
33840 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c  a [BLOB handle |
33850 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20   handle] to the 
33860 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20  BLOB located.** 
33870 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c  in row iRow, col
33880 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62  umn zColumn, tab
33890 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74  le zTable in dat
338a0 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e  abase zDb;.** in
338b0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
338c0 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74  e same BLOB that
338d0 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74   would be select
338e0 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  ed by:.**.** <pr
338f0 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54  e>.**     SELECT
33900 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44   zColumn FROM zD
33910 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b  b.zTable WHERE [
33920 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a  rowid] = iRow;.*
33930 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
33940 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20 70   ^If the flags p
33950 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d  arameter is non-
33960 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42  zero, then the B
33970 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  LOB is opened fo
33980 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72  r read.** and wr
33990 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20  ite access. ^If 
339a0 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20  it is zero, the 
339b0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
339c0 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a  or read access..
339d0 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f  ** ^It is not po
339e0 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61  ssible to open a
339f0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20   column that is 
33a00 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78  part of an index
33a10 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20   or primary .** 
33a20 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e  key for writing.
33a30 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65   ^If [foreign ke
33a40 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61  y constraints] a
33a50 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69  re enabled, it i
33a60 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62  s .** not possib
33a70 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c  le to open a col
33a80 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72 74  umn that is part
33a90 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79   of a [child key
33aa0 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a  ] for writing..*
33ab0 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20  *.** ^Note that 
33ac0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d  the database nam
33ad0 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c  e is not the fil
33ae0 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61  ename that conta
33af0 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ins.** the datab
33b00 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20 74  ase but rather t
33b10 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65  he symbolic name
33b20 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
33b30 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73   that.** appears
33b40 20 61 66 74 65 72 20 74 68 65 20 41 53 20 6b 65   after the AS ke
33b50 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64  yword when the d
33b60 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65  atabase is conne
33b70 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41  cted using [ATTA
33b80 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  CH]..** ^For the
33b90 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
33ba0 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61 73  ile, the databas
33bb0 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22  e name is "main"
33bc0 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74  ..** ^For TEMP t
33bd0 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62  ables, the datab
33be0 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d  ase name is "tem
33bf0 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73  p"..**.** ^(On s
33c00 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f  uccess, [SQLITE_
33c10 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OK] is returned 
33c20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f  and the new [BLO
33c30 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69  B handle] is wri
33c40 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c  tten.** to *ppBl
33c50 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e  ob. Otherwise an
33c60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
33c70 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70   returned and *p
33c80 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20  pBlob is set.** 
33c90 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69  to be a null poi
33ca0 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73  nter.)^.** ^This
33cb0 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
33cc0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
33cd0 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63  nection] error c
33ce0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a  ode and message.
33cf0 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76 69  ** accessible vi
33d00 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  a [sqlite3_errco
33d10 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  de()] and [sqlit
33d20 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64  e3_errmsg()] and
33d30 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63   related.** func
33d40 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61  tions. ^Note tha
33d50 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61  t the *ppBlob va
33d60 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73  riable is always
33d70 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20   initialized in 
33d80 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61  a.** way that ma
33d90 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20 69  kes it safe to i
33da0 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62  nvoke [sqlite3_b
33db0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20  lob_close()] on 
33dc0 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72  *ppBlob.** regar
33dd0 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
33de0 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20  cess or failure 
33df0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e  of this routine.
33e00 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
33e10 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20  row that a BLOB 
33e20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f  handle points to
33e30 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20   is modified by 
33e40 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20  an.** [UPDATE], 
33e50 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20  [DELETE], or by 
33e60 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69  [ON CONFLICT] si
33e70 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68  de-effects.** th
33e80 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64  en the BLOB hand
33e90 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20  le is marked as 
33ea0 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68  "expired"..** Th
33eb0 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61 6e  is is true if an
33ec0 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  y column of the 
33ed0 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20  row is changed, 
33ee0 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  even a column.**
33ef0 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65 20   other than the 
33f00 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e  one the BLOB han
33f10 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29  dle is open on.)
33f20 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b  ^.** ^Calls to [
33f30 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
33f40 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
33f50 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20  3_blob_write()] 
33f60 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64  for.** a expired
33f70 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69   BLOB handle fai
33f80 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e  l with an return
33f90 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
33fa0 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68  _ABORT]..** ^(Ch
33fb0 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e  anges written in
33fc0 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20  to a BLOB prior 
33fd0 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69  to the BLOB expi
33fe0 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ring are not.** 
33ff0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74  rolled back by t
34000 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66  he expiration of
34010 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68   the BLOB.  Such
34020 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76   changes will ev
34030 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d  entually.** comm
34040 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73 61  it if the transa
34050 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20  ction continues 
34060 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e  to completion.)^
34070 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20  .**.** ^Use the 
34080 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
34090 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
340a0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
340b0 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65  e size of.** the
340c0 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e   opened blob.  ^
340d0 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c  The size of a bl
340e0 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68  ob may not be ch
340f0 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  anged by this.**
34100 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65   interface.  Use
34110 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51   the [UPDATE] SQ
34120 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61  L command to cha
34130 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  nge the size of 
34140 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a  a.** blob..**.**
34150 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
34160 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ind_zeroblob()] 
34170 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
34180 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20  ult_zeroblob()] 
34190 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e  interfaces.** an
341a0 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b  d the built-in [
341b0 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75  zeroblob] SQL fu
341c0 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  nction can be us
341d0 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a  ed, if desired,.
341e0 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20  ** to create an 
341f0 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c  empty, zero-fill
34200 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68  ed blob in which
34210 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
34220 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20  e using.** this 
34230 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
34240 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f   To avoid a reso
34250 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79  urce leak, every
34260 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
34270 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74  le] should event
34280 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65  ually.** be rele
34290 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74  ased by a call t
342a0 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  o [sqlite3_blob_
342b0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  close()]..*/.int
342c0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70   sqlite3_blob_op
342d0 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  en(.  sqlite3*,.
342e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44    const char *zD
342f0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
34300 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74  *zTable,.  const
34310 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a   char *zColumn,.
34320 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20    sqlite3_int64 
34330 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67  iRow,.  int flag
34340 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f  s,.  sqlite3_blo
34350 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f  b **ppBlob.);../
34360 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
34370 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e 64  lose A BLOB Hand
34380 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65 73  le.**.** ^Closes
34390 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68   an open [BLOB h
343a0 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  andle]..**.** ^C
343b0 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73 68  losing a BLOB sh
343c0 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63 75  all cause the cu
343d0 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
343e0 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20 69  n to commit.** i
343f0 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 6f  f there are no o
34400 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20 70  ther BLOBs, no p
34410 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64 20  ending prepared 
34420 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64 20  statements, and 
34430 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
34440 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69 6e  connection is in
34450 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   [autocommit mod
34460 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 77  e]..** ^If any w
34470 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65 20  rites were made 
34480 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68 65  to the BLOB, the
34490 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64 20  y might be held 
344a0 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74 69  in cache.** unti
344b0 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65 72  l the close oper
344c0 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77 69  ation if they wi
344d0 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ll fit..**.** ^(
344e0 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f 42  Closing the BLOB
344f0 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74 68   often forces th
34500 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75 74  e changes.** out
34510 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f 20   to disk and so 
34520 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f 72  if any I/O error
34530 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77 69  s occur, they wi
34540 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72 0a  ll likely occur.
34550 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ** at the time w
34560 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73 20  hen the BLOB is 
34570 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72 72  closed.  Any err
34580 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 64  ors that occur d
34590 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e 67  uring.** closing
345a0 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61 73   are reported as
345b0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75   a non-zero retu
345c0 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a 2a  rn value.)^.**.*
345d0 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69 73 20  * ^(The BLOB is 
345e0 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74 69  closed unconditi
345f0 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69 66  onally.  Even if
34600 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
34610 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72 6f  turns.** an erro
34620 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f 42  r code, the BLOB
34630 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65 64   is still closed
34640 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  .)^.**.** ^Calli
34650 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
34660 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69 6e  with a null poin
34670 74 65 72 20 28 73 75 63 68 20 61 73 20 77 6f 75  ter (such as wou
34680 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 0a 2a  ld be returned.*
34690 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20 63 61  * by a failed ca
346a0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
346b0 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73 20  lob_open()]) is 
346c0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
346d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
346e0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c 69  _blob_close(sqli
346f0 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f 2a  te3_blob *);../*
34700 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
34710 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f 66  turn The Size Of
34720 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a   An Open BLOB.**
34730 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74 68 65  .** ^Returns the
34740 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20 6f   size in bytes o
34750 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65 73  f the BLOB acces
34760 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 0a 2a  sible via the .*
34770 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 6f  * successfully o
34780 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64  pened [BLOB hand
34790 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79 20  le] in its only 
347a0 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 0a  argument.  ^The.
347b0 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 62  ** incremental b
347c0 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65 73  lob I/O routines
347d0 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20 6f   can only read o
347e0 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20 65 78  r overwriting ex
347f0 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20 63  isting.** blob c
34800 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63 61 6e  ontent; they can
34810 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 73  not change the s
34820 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a 2a  ize of a blob..*
34830 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
34840 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20  e only works on 
34850 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20  a [BLOB handle] 
34860 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20 63  which has been c
34870 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70  reated.** by a p
34880 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
34890 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
348a0 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e  _blob_open()] an
348b0 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a  d which has not.
348c0 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62  ** been closed b
348d0 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  y [sqlite3_blob_
348e0 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69  close()].  Passi
348f0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69  ng any other poi
34900 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68  nter in.** to th
34910 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c  is routine resul
34920 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
34930 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64  and probably und
34940 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
34950 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
34960 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71 6c  3_blob_bytes(sql
34970 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f  ite3_blob *);../
34980 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
34990 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41 20  ead Data From A 
349a0 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61 6c  BLOB Incremental
349b0 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ly.**.** ^(This 
349c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
349d0 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66 72   to read data fr
349e0 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42  om an open [BLOB
349f0 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61 0a   handle] into a.
34a00 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c 69  ** caller-suppli
34a10 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79 74  ed buffer. N byt
34a20 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20 63  es of data are c
34a30 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66 65  opied into buffe
34a40 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  r Z.** from the 
34a50 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74  open BLOB, start
34a60 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f  ing at offset iO
34a70 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ffset.)^.**.** ^
34a80 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73 65  If offset iOffse
34a90 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 4e  t is less than N
34aa0 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65 20   bytes from the 
34ab0 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42 2c  end of the BLOB,
34ac0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
34ad0 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  R] is returned a
34ae0 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72 65  nd no data is re
34af0 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20 69 4f  ad.  ^If N or iO
34b00 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73 73  ffset is.** less
34b10 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51 4c   than zero, [SQL
34b20 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72 65  ITE_ERROR] is re
34b30 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64 61  turned and no da
34b40 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20 5e  ta is read..** ^
34b50 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
34b60 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65 20  blob (and hence 
34b70 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c 75  the maximum valu
34b80 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29 0a  e of N+iOffset).
34b90 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
34ba0 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
34bb0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74  sqlite3_blob_byt
34bc0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  es()] interface.
34bd0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65 6d  .**.** ^An attem
34be0 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d 20  pt to read from 
34bf0 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f 42  an expired [BLOB
34c00 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20 77   handle] fails w
34c10 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  ith an.** error 
34c20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  code of [SQLITE_
34c30 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ABORT]..**.** ^(
34c40 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c 69  On success, sqli
34c50 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 20  te3_blob_read() 
34c60 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f  returns SQLITE_O
34c70 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c  K..** Otherwise,
34c80 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
34c90 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64   or an [extended
34ca0 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20   error code] is 
34cb0 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
34cc0 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f  * This routine o
34cd0 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b  nly works on a [
34ce0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69  BLOB handle] whi
34cf0 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61  ch has been crea
34d00 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f  ted.** by a prio
34d10 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  r successful cal
34d20 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c  l to [sqlite3_bl
34d30 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77  ob_open()] and w
34d40 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20  hich has not.** 
34d50 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b  been closed by [
34d60 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
34d70 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20  se()].  Passing 
34d80 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65  any other pointe
34d90 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20  r in.** to this 
34da0 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20  routine results 
34db0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
34dc0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
34dd0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a  rable behavior..
34de0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
34df0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
34e00 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ite()]..*/.int s
34e10 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
34e20 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c  (sqlite3_blob *,
34e30 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e 2c   void *Z, int N,
34e40 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a   int iOffset);..
34e50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34e60 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f 20  Write Data Into 
34e70 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74  A BLOB Increment
34e80 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ally.**.** ^This
34e90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
34ea0 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61 20  d to write data 
34eb0 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42 4c  into an open [BL
34ec0 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d 20  OB handle] from 
34ed0 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70  a.** caller-supp
34ee0 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e 4e 20  lied buffer. ^N 
34ef0 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61 72  bytes of data ar
34f00 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74 68  e copied from th
34f10 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69 6e  e buffer Z.** in
34f20 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f 42  to the open BLOB
34f30 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f 66  , starting at of
34f40 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a 2a  fset iOffset..**
34f50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42 4c 4f  .** ^If the [BLO
34f60 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65 64  B handle] passed
34f70 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
34f80 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20 6f  gument was not o
34f90 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72 69  pened for.** wri
34fa0 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73 20  ting (the flags 
34fb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
34fc0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
34fd0 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a 2a  )] was zero),.**
34fe0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
34ff0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 52  eturns [SQLITE_R
35000 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a 20  EADONLY]..**.** 
35010 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d  ^This function m
35020 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20 74  ay only modify t
35030 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
35040 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a 2a  he BLOB; it is.*
35050 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  * not possible t
35060 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20 73  o increase the s
35070 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75 73  ize of a BLOB us
35080 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a 2a  ing this API..**
35090 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66   ^If offset iOff
350a0 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  set is less than
350b0 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68   N bytes from th
350c0 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f  e end of the BLO
350d0 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  B,.** [SQLITE_ER
350e0 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
350f0 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
35100 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 20 4e 20  written.  ^If N 
35110 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
35120 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52 52  zero [SQLITE_ERR
35130 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
35140 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 77  and no data is w
35150 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20 73  ritten..** The s
35160 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ize of the BLOB 
35170 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d  (and hence the m
35180 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20  aximum value of 
35190 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61  N+iOffset).** ca
351a0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
351b0 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  using the [sqlit
351c0 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
351d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
351e0 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f  * ^An attempt to
351f0 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78 70   write to an exp
35200 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ired [BLOB handl
35210 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  e] fails with an
35220 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f  .** error code o
35230 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d  f [SQLITE_ABORT]
35240 2e 20 20 5e 57 72 69 74 65 73 20 74 6f 20 74 68  .  ^Writes to th
35250 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63 75  e BLOB that occu
35260 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20 74  rred.** before t
35270 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  he [BLOB handle]
35280 20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f 74   expired are not
35290 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20   rolled back by 
352a0 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69 6f  the.** expiratio
352b0 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65 2c  n of the handle,
352c0 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73   though of cours
352d0 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  e those changes 
352e0 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62 65  might.** have be
352f0 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  en overwritten b
35300 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
35310 74 68 61 74 20 65 78 70 69 72 65 64 20 74 68 65  that expired the
35320 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a 20   BLOB handle.** 
35330 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64 65  or by other inde
35340 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65 6e  pendent statemen
35350 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73  ts..**.** ^(On s
35360 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65 33 5f  uccess, sqlite3_
35370 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 72 65 74  blob_write() ret
35380 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a  urns SQLITE_OK..
35390 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61 6e  ** Otherwise, an
353a0 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f    [error code] o
353b0 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20 65  r an [extended e
353c0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
353d0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
353e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c  This routine onl
353f0 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c  y works on a [BL
35400 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68  OB handle] which
35410 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74 65   has been create
35420 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20  d.** by a prior 
35430 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
35440 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
35450 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69  _open()] and whi
35460 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65  ch has not.** be
35470 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71  en closed by [sq
35480 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
35490 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e  ()].  Passing an
354a0 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20  y other pointer 
354b0 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f  in.** to this ro
354c0 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e  utine results in
354d0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
354e0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
354f0 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ble behavior..**
35500 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
35510 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64  qlite3_blob_read
35520 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
35530 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 73  te3_blob_write(s
35540 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20 63  qlite3_blob *, c
35550 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69 6e  onst void *z, in
35560 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65 74  t n, int iOffset
35570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35580 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69 6c 65  EF: Virtual File
35590 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73 0a   System Objects.
355a0 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c 20  **.** A virtual 
355b0 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53 29  filesystem (VFS)
355c0 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   is an [sqlite3_
355d0 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 74  vfs] object.** t
355e0 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73 20  hat SQLite uses 
355f0 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20 77  to interact.** w
35600 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ith the underlyi
35610 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
35620 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69 74  tem.  Most SQLit
35630 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77 69  e builds come wi
35640 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 64  th a.** single d
35650 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 74 20  efault VFS that 
35660 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  is appropriate f
35670 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d 70  or the host comp
35680 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46 53  uter..** New VFS
35690 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  es can be regist
356a0 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 69 6e  ered and existin
356b0 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 20 75  g VFSes can be u
356c0 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 20  nregistered..** 
356d0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  The following in
356e0 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
356f0 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  vided..**.** ^Th
35700 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69  e sqlite3_vfs_fi
35710 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  nd() interface r
35720 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
35730 20 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e 20   to a VFS given 
35740 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e 61  its name..** ^Na
35750 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65 6e  mes are case sen
35760 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d 65  sitive..** ^Name
35770 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  s are zero-termi
35780 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
35790 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 72  ngs..** ^If ther
357a0 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20 61  e is no match, a
357b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
357c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49   returned..** ^I
357d0 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e 55  f zVfsName is NU
357e0 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66 61  LL then the defa
357f0 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75 72  ult VFS is retur
35800 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77 20  ned..**.** ^New 
35810 56 46 53 65 73 20 61 72 65 20 72 65 67 69 73 74  VFSes are regist
35820 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 74 65  ered with sqlite
35830 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
35840 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77 20 56  ..** ^Each new V
35850 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20 64  FS becomes the d
35860 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 74 68  efault VFS if th
35870 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67 20  e makeDflt flag 
35880 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  is set..** ^The 
35890 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65 20  same VFS can be 
358a0 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69  registered multi
358b0 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f 75  ple times withou
358c0 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54 6f  t injury..** ^To
358d0 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69 6e   make an existin
358e0 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20 64  g VFS into the d
358f0 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67 69  efault VFS, regi
35900 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a 2a  ster it again.**
35910 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44 66   with the makeDf
35920 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49 66  lt flag set.  If
35930 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20 56   two different V
35940 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a 2a  FSes with the.**
35950 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 72   same name are r
35960 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20 62  egistered, the b
35970 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
35980 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20 56  ined.  If a.** V
35990 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65 64  FS is registered
359a0 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68 61   with a name tha
359b0 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e 20  t is NULL or an 
359c0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a 2a  empty string,.**
359d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
359e0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
359f0 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69 73 74  .**.** ^Unregist
35a00 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74 68  er a VFS with th
35a10 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e  e sqlite3_vfs_un
35a20 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65 72  register() inter
35a30 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20 74 68  face..** ^(If th
35a40 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73  e default VFS is
35a50 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20 61   unregistered, a
35a60 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63 68  nother VFS is ch
35a70 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20 64  osen as.** the d
35a80 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68 6f  efault.  The cho
35a90 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77 20  ice for the new 
35aa0 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72 79  VFS is arbitrary
35ab0 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76  .)^.*/.sqlite3_v
35ac0 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73 5f  fs *sqlite3_vfs_
35ad0 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72 20  find(const char 
35ae0 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74 20  *zVfsName);.int 
35af0 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69  sqlite3_vfs_regi
35b00 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66 73  ster(sqlite3_vfs
35b10 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74 29  *, int makeDflt)
35b20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 66  ;.int sqlite3_vf
35b30 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71 6c  s_unregister(sql
35b40 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a 0a  ite3_vfs*);../*.
35b50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
35b60 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  exes.**.** The S
35b70 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
35b80 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  these routines f
35b90 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79 6e  or thread.** syn
35ba0 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54 68  chronization. Th
35bb0 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 69 6e  ough they are in
35bc0 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65 72  tended for inter
35bd0 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53 51  nal.** use by SQ
35be0 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74 20  Lite, code that 
35bf0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53 51  links against SQ
35c00 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d 69  Lite is.** permi
35c10 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79 20  tted to use any 
35c20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
35c30 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  s..**.** The SQL
35c40 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20  ite source code 
35c50 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70 6c  contains multipl
35c60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
35c70 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d 75  s.** of these mu
35c80 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20 41  tex routines.  A
35c90 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69 6d  n appropriate im
35ca0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
35cb0 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74 6f  is selected auto
35cc0 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f 6d  matically at com
35cd0 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28 54 68  pile-time.  ^(Th
35ce0 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 69  e following.** i
35cf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 61  mplementations a
35d00 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  re available in 
35d10 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 3a  the SQLite core:
35d20 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
35d30 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55 54  li>   SQLITE_MUT
35d40 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20 20  EX_OS2.** <li>  
35d50 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
35d60 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20 20  HREAD.** <li>   
35d70 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33 32  SQLITE_MUTEX_W32
35d80 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49 54  .** <li>   SQLIT
35d90 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a 20  E_MUTEX_NOOP.** 
35da0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  </ul>)^.**.** ^T
35db0 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  he SQLITE_MUTEX_
35dc0 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61 74  NOOP implementat
35dd0 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66 20  ion is a set of 
35de0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61 74  routines.** that
35df0 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c 6f   does no real lo
35e00 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70 70  cking and is app
35e10 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73 65  ropriate for use
35e20 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 2d   in.** a single-
35e30 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
35e40 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51 4c 49  tion.  ^The SQLI
35e50 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a 2a  TE_MUTEX_OS2,.**
35e60 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50 54   SQLITE_MUTEX_PT
35e70 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49 54  HREAD, and SQLIT
35e80 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70 6c  E_MUTEX_W32 impl
35e90 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61  ementations.** a
35ea0 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 66  re appropriate f
35eb0 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c 20  or use on OS/2, 
35ec0 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f 77  Unix, and Window
35ed0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  s..**.** ^(If SQ
35ee0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
35ef0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
35f00 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70 72  _MUTEX_APPDEF pr
35f10 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d 61  eprocessor.** ma
35f20 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69 74  cro defined (wit
35f30 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54 45  h "-DSQLITE_MUTE
35f40 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74 68  X_APPDEF=1"), th
35f50 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20 69  en no mutex.** i
35f60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
35f70 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20 74   included with t
35f80 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20 74  he library. In t
35f90 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a 20  his case the.** 
35fa0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
35fb0 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f 6d   supply a custom
35fc0 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e 74   mutex implement
35fd0 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65 0a  ation using the.
35fe0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
35ff0 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 20  G_MUTEX] option 
36000 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  of the sqlite3_c
36010 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f 6e  onfig() function
36020 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c 69  .** before calli
36030 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ng sqlite3_initi
36040 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20 6f  alize() or any o
36050 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c 69  ther public sqli
36060 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  te3_.** function
36070 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c 69   that calls sqli
36080 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
36090 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
360a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
360b0 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c 6c  oc() routine all
360c0 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a 20  ocates a new.** 
360d0 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72 6e  mutex and return
360e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
360f0 74 2e 20 5e 49 66 20 69 74 20 72 65 74 75 72 6e  t. ^If it return
36100 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20 6d  s NULL.** that m
36110 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74 65  eans that a mute
36120 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61  x could not be a
36130 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51 4c 69  llocated.  ^SQLi
36140 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69 6e  te.** will unwin
36150 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64 20  d its stack and 
36160 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72 2e  return an error.
36170 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74    ^(The argument
36180 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  .** to sqlite3_m
36190 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73 20  utex_alloc() is 
361a0 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
361b0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a 0a  eger constants:.
361c0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
361d0 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
361e0 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20 53  _FAST.** <li>  S
361f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43 55  QLITE_MUTEX_RECU
36200 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  RSIVE.** <li>  S
36210 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
36220 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c 69  IC_MASTER.** <li
36230 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  >  SQLITE_MUTEX_
36240 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c 6c  STATIC_MEM.** <l
36250 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
36260 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a 20  _STATIC_MEM2.** 
36270 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54  <li>  SQLITE_MUT
36280 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a 2a  EX_STATIC_PRNG.*
36290 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d  * <li>  SQLITE_M
362a0 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 0a  UTEX_STATIC_LRU.
362b0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
362c0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
362d0 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  2.** </ul>)^.**.
362e0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 77  ** ^The first tw
362f0 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28 53 51 4c  o constants (SQL
36300 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20 61  ITE_MUTEX_FAST a
36310 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  nd SQLITE_MUTEX_
36320 52 45 43 55 52 53 49 56 45 29 0a 2a 2a 20 63 61  RECURSIVE).** ca
36330 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  use sqlite3_mute
36340 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72 65  x_alloc() to cre
36350 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75 74  ate.** a new mut
36360 65 78 2e 20 20 5e 54 68 65 20 6e 65 77 20 6d 75  ex.  ^The new mu
36370 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76 65  tex is recursive
36380 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54   when SQLITE_MUT
36390 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a 20  EX_RECURSIVE.** 
363a0 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74 20  is used but not 
363b0 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20 77  necessarily so w
363c0 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  hen SQLITE_MUTEX
363d0 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 0a 2a  _FAST is used..*
363e0 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70 6c  * The mutex impl
363f0 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73 20  ementation does 
36400 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b 65  not need to make
36410 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a   a distinction.*
36420 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
36430 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45  _MUTEX_RECURSIVE
36440 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45   and SQLITE_MUTE
36450 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f 65  X_FAST if it doe
36460 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 6f  s.** not want to
36470 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
36480 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20 72  only request a r
36490 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 20 69  ecursive mutex i
364a0 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72 65  n.** cases where
364b0 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64 73   it really needs
364c0 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20 66 61 73   one.  ^If a fas
364d0 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69 76  ter non-recursiv
364e0 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c 65  e mutex.** imple
364f0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76 61  mentation is ava
36500 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68 6f  ilable on the ho
36510 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68 65  st platform, the
36520 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 65 6d   mutex subsystem
36530 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72 6e  .** might return
36540 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 69 6e   such a mutex in
36550 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51 4c   response to SQL
36560 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e 0a  ITE_MUTEX_FAST..
36570 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 68 65 72  **.** ^The other
36580 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65 74   allowed paramet
36590 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 6d  ers to sqlite3_m
365a0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 28 61 6e  utex_alloc() (an
365b0 79 74 68 69 6e 67 20 6f 74 68 65 72 0a 2a 2a 20  ything other.** 
365c0 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  than SQLITE_MUTE
365d0 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c 49 54  X_FAST and SQLIT
365e0 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
365f0 45 29 20 65 61 63 68 20 72 65 74 75 72 6e 0a 2a  E) each return.*
36600 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
36610 20 73 74 61 74 69 63 20 70 72 65 65 78 69 73 74   static preexist
36620 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e 53 69 78  ing mutex.  ^Six
36630 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 20   static mutexes 
36640 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20 74  are.** used by t
36650 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73 69  he current versi
36660 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 46  on of SQLite.  F
36670 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
36680 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79 20  f SQLite.** may 
36690 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  add additional s
366a0 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20 20  tatic mutexes.  
366b0 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 20 61  Static mutexes a
366c0 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c 0a  re for internal.
366d0 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74 65  ** use by SQLite
366e0 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
366f0 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53 51  ions that use SQ
36700 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73 68 6f  Lite mutexes sho
36710 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79 20  uld.** use only 
36720 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74 65  the dynamic mute
36730 78 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  xes returned by 
36740 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53  SQLITE_MUTEX_FAS
36750 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d  T or.** SQLITE_M
36760 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e 0a  UTEX_RECURSIVE..
36770 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
36780 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20 64   if one of the d
36790 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61 72  ynamic mutex par
367a0 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45 5f  ameters (SQLITE_
367b0 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f 72  MUTEX_FAST.** or
367c0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
367d0 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65 64  CURSIVE) is used
367e0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 75   then sqlite3_mu
367f0 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20 72  tex_alloc().** r
36800 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72 65  eturns a differe
36810 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65 72  nt mutex on ever
36820 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74 20 66 6f  y call.  ^But fo
36830 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a 20  r the static.** 
36840 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 68 65  mutex types, the
36850 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20 72   same mutex is r
36860 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72 79  eturned on every
36870 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a 2a   call that has.*
36880 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65 20  * the same type 
36890 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
368a0 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  he sqlite3_mutex
368b0 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
368c0 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70 72  deallocates a pr
368d0 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c 6f  eviously.** allo
368e0 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d 75  cated dynamic mu
368f0 74 65 78 2e 20 20 5e 53 51 4c 69 74 65 20 69 73  tex.  ^SQLite is
36900 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61 6c   careful to deal
36910 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a 20  locate every.** 
36920 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74 68  dynamic mutex th
36930 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73 2e  at it allocates.
36940 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d 75    The dynamic mu
36950 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20 62  texes must not b
36960 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65 6e  e in.** use when
36970 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c 6f   they are deallo
36980 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70 74 69  cated.  Attempti
36990 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74 65  ng to deallocate
369a0 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75 74   a static.** mut
369b0 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ex results in un
369c0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
369d0 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65 76 65 72  .  ^SQLite never
369e0 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a 20   deallocates.** 
369f0 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  a static mutex..
36a00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36a10 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29  e3_mutex_enter()
36a20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75 74   and sqlite3_mut
36a30 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e 65  ex_try() routine
36a40 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f 20  s attempt.** to 
36a50 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20 20  enter a mutex.  
36a60 5e 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65  ^If another thre
36a70 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77 69  ad is already wi
36a80 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c 0a  thin the mutex,.
36a90 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
36aa0 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62 6c  _enter() will bl
36ab0 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ock and sqlite3_
36ac0 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c 6c  mutex_try() will
36ad0 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
36ae0 45 5f 42 55 53 59 2e 20 20 5e 54 68 65 20 73 71  E_BUSY.  ^The sq
36af0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79 28  lite3_mutex_try(
36b00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
36b10 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 0a  rns [SQLITE_OK].
36b20 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73 66  ** upon successf
36b30 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28 4d 75 74  ul entry.  ^(Mut
36b40 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73 69  exes created usi
36b50 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55 54  ng.** SQLITE_MUT
36b60 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61 6e  EX_RECURSIVE can
36b70 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c 74   be entered mult
36b80 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74 68  iple times by th
36b90 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a 2a  e same thread..*
36ba0 2a 20 49 6e 20 73 75 63 68 20 63 61 73 65 73 20  * In such cases 
36bb0 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d 75  the,.** mutex mu
36bc0 73 74 20 62 65 20 65 78 69 74 65 64 20 61 6e 20  st be exited an 
36bd0 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  equal number of 
36be0 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e 6f  times before ano
36bf0 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 63  ther thread.** c
36c00 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20 5e 28 49  an enter.)^  ^(I
36c10 66 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  f the same threa
36c20 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65 72  d tries to enter
36c30 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b 69   any other.** ki
36c40 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72 65  nd of mutex more
36c50 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65 20   than once, the 
36c60 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
36c70 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65  fined..** SQLite
36c80 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68 69   will never exhi
36c90 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68 61  bit.** such beha
36ca0 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e 20  vior in its own 
36cb0 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e 29  use of mutexes.)
36cc0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20 73  ^.**.** ^(Some s
36cd0 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61 6d  ystems (for exam
36ce0 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35 29  ple, Windows 95)
36cf0 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20   do not support 
36d00 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
36d10 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
36d20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72  sqlite3_mutex_tr
36d30 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20 73  y().  On those s
36d40 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33 5f  ystems, sqlite3_
36d50 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20 77  mutex_try().** w
36d60 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72  ill always retur
36d70 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20  n SQLITE_BUSY.  
36d80 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
36d90 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a 2a  only ever uses.*
36da0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
36db0 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74 69  try() as an opti
36dc0 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69 73  mization so this
36dd0 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 62   is acceptable b
36de0 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a 2a  ehavior.)^.**.**
36df0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75   ^The sqlite3_mu
36e00 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75 74  tex_leave() rout
36e10 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74 65  ine exits a mute
36e20 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70 72  x that was.** pr
36e30 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65 64  eviously entered
36e40 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68 72   by the same thr
36e50 65 61 64 2e 20 20 20 5e 28 54 68 65 20 62 65 68  ead.   ^(The beh
36e60 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65  avior.** is unde
36e70 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75 74  fined if the mut
36e80 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  ex is not curren
36e90 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20 74  tly entered by t
36ea0 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74 68  he.** calling th
36eb0 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20 63  read or is not c
36ec0 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61 74  urrently allocat
36ed0 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  ed.  SQLite will
36ee0 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69 74  .** never do eit
36ef0 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  her.)^.**.** ^If
36f00 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
36f10 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65   sqlite3_mutex_e
36f20 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33 5f  nter(), sqlite3_
36f30 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72 0a  mutex_try(), or.
36f40 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
36f50 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e 55  _leave() is a NU
36f60 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
36f70 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74 69   all three routi
36f80 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61 73  nes.** behave as
36f90 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 53   no-ops..**.** S
36fa0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
36fb0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d 20  3_mutex_held()] 
36fc0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  and [sqlite3_mut
36fd0 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a 2a  ex_notheld()]..*
36fe0 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  /.sqlite3_mutex 
36ff0 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  *sqlite3_mutex_a
37000 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
37010 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66 72  sqlite3_mutex_fr
37020 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ee(sqlite3_mutex
37030 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
37040 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71 6c  _mutex_enter(sql
37050 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e  ite3_mutex*);.in
37060 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  t sqlite3_mutex_
37070 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  try(sqlite3_mute
37080 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  x*);.void sqlite
37090 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73 71  3_mutex_leave(sq
370a0 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 0a  lite3_mutex*);..
370b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
370c0 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f 62  Mutex Methods Ob
370d0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
370e0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73  stance of this s
370f0 74 72 75 63 74 75 72 65 20 64 65 66 69 6e 65 73  tructure defines
37100 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 72   the low-level r
37110 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64 20  outines.** used 
37120 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64 20  to allocate and 
37130 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a 0a  use mutexes..**.
37140 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65 20  ** Usually, the 
37150 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69 6d  default mutex im
37160 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70 72  plementations pr
37170 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 74 65  ovided by SQLite
37180 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69 65   are.** sufficie
37190 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  nt, however the 
371a0 75 73 65 72 20 68 61 73 20 74 68 65 20 6f 70 74  user has the opt
371b0 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75 74  ion of substitut
371c0 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a 20  ing a custom.** 
371d0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
371e0 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20 64  or specialized d
371f0 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73 79  eployments or sy
37200 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68 20  stems for which 
37210 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e  SQLite.** does n
37220 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 75 69  ot provide a sui
37230 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
37240 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63 61  tion. In this ca
37250 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a 20  se, the user.** 
37260 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70 75  creates and popu
37270 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e 63  lates an instanc
37280 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74  e of this struct
37290 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20 74  ure to pass.** t
372a0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
372b0 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74 68  () along with th
372c0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
372d0 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e 0a  _MUTEX] option..
372e0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  ** Additionally,
372f0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
37300 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  this structure c
37310 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 61 6e  an be used as an
37320 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69 61  .** output varia
37330 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69 6e  ble when queryin
37340 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f 72  g the system for
37350 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75 74   the current mut
37360 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ex.** implementa
37370 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65 20  tion, using the 
37380 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
37390 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e  ETMUTEX] option.
373a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74  .**.** ^The xMut
373b0 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64 65  exInit method de
373c0 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73 74  fined by this st
373d0 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f 6b  ructure is invok
373e0 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66  ed as.** part of
373f0 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c 69   system initiali
37400 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73 71  zation by the sq
37410 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
37420 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20  () function..** 
37430 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74 20  ^The xMutexInit 
37440 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
37450 20 62 79 20 53 51 4c 69 74 65 20 65 78 61 63 74   by SQLite exact
37460 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ly once for each
37470 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20 63 61  .** effective ca
37480 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 69  ll to [sqlite3_i
37490 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  nitialize()]..**
374a0 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78 45  .** ^The xMutexE
374b0 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69 6e 65  nd method define
374c0 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63 74  d by this struct
374d0 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ure is invoked a
374e0 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79 73  s.** part of sys
374f0 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62 79 20  tem shutdown by 
37500 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  the sqlite3_shut
37510 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e 2e  down() function.
37520 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   The.** implemen
37530 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20 6d  tation of this m
37540 65 74 68 6f 64 20 69 73 20 65 78 70 65 63 74 65  ethod is expecte
37550 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c 6c  d to release all
37560 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a 20   outstanding.** 
37570 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61 69 6e  resources obtain
37580 65 64 20 62 79 20 74 68 65 20 6d 75 74 65 78 20  ed by the mutex 
37590 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65 6e  methods implemen
375a0 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69 61 6c  tation, especial
375b0 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74 61  ly.** those obta
375c0 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d 75 74  ined by the xMut
375d0 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20 20  exInit method.  
375e0 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28 29  ^The xMutexEnd()
375f0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
37600 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c 79   invoked exactly
37610 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 63   once for each c
37620 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37630 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 0a  shutdown()]..**.
37640 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61 69 6e 69  ** ^(The remaini
37650 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f 64 73  ng seven methods
37660 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69 73   defined by this
37670 20 73 74 72 75 63 74 75 72 65 20 28 78 4d 75 74   structure (xMut
37680 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75 74  exAlloc,.** xMut
37690 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78 45 6e  exFree, xMutexEn
376a0 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79 2c 20  ter, xMutexTry, 
376b0 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78 4d 75  xMutexLeave, xMu
376c0 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20 78  texHeld and.** x
376d0 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20 69 6d  MutexNotheld) im
376e0 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c 6c  plement the foll
376f0 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73  owing interfaces
37700 20 28 72 65 73 70 65 63 74 69 76 65 6c 79 29 3a   (respectively):
37710 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
37720 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33 5f   <li>  [sqlite3_
37730 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20 3c  mutex_alloc()] <
37740 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 20  /li>.**   <li>  
37750 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66  [sqlite3_mutex_f
37760 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  ree()] </li>.** 
37770 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
37780 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 5d 20  _mutex_enter()] 
37790 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
377a0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
377b0 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20  try()] </li>.** 
377c0 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
377d0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 5d 20  _mutex_leave()] 
377e0 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
377f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
37800 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  held()] </li>.**
37810 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
37820 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
37830 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  )] </li>.** </ul
37840 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 6e  >)^.**.** The on
37850 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ly difference is
37860 20 74 68 61 74 20 74 68 65 20 70 75 62 6c 69 63   that the public
37870 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66 75 6e   sqlite3_XXX fun
37880 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74 65  ctions enumerate
37890 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65 6e  d.** above silen
378a0 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79 20 69  tly ignore any i
378b0 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20  nvocations that 
378c0 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  pass a NULL poin
378d0 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ter instead.** o
378e0 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20  f a valid mutex 
378f0 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70 6c  handle. The impl
37900 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
37910 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66 69 6e  he methods defin
37920 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 73 74  ed.** by this st
37930 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f 74 20  ructure are not 
37940 72 65 71 75 69 72 65 64 20 74 6f 20 68 61 6e 64  required to hand
37950 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20 74 68  le this case, th
37960 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66 20  e results.** of 
37970 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  passing a NULL p
37980 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
37990 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78 20  f a valid mutex 
379a0 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64 65 66  handle are undef
379b0 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69 74  ined.** (i.e. it
379c0 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20 74   is acceptable t
379d0 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d 70  o provide an imp
379e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
379f0 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a 2a 2a   segfaults if.**
37a00 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61 20   it is passed a 
37a10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a 2a  NULL pointer)..*
37a20 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78 49  *.** The xMutexI
37a30 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 6d 75 73  nit() method mus
37a40 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
37a50 20 20 5e 49 74 20 6d 75 73 74 20 62 65 20 68 61    ^It must be ha
37a60 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 69 6e 76  rmless to.** inv
37a70 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 74 28 29  oke xMutexInit()
37a80 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 73 20 77   mutiple times w
37a90 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70  ithin the same p
37aa0 72 6f 63 65 73 73 20 61 6e 64 20 77 69 74 68 6f  rocess and witho
37ab0 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 6e 69 6e  ut.** intervenin
37ac0 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d 75 74 65  g calls to xMute
37ad0 78 45 6e 64 28 29 2e 20 20 53 65 63 6f 6e 64 20  xEnd().  Second 
37ae0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
37af0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75 74 65  alls to.** xMute
37b00 78 49 6e 69 74 28 29 20 6d 75 73 74 20 62 65 20  xInit() must be 
37b10 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 78  no-ops..**.** ^x
37b20 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73 74  MutexInit() must
37b30 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20   not use SQLite 
37b40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
37b50 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  n ([sqlite3_mall
37b60 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69 74 73  oc()].** and its
37b70 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20 20 5e   associates).  ^
37b80 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75 74 65  Similarly, xMute
37b90 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20 6e 6f  xAlloc() must no
37ba0 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65 6d  t use SQLite mem
37bb0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
37bc0 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63 20 6d  n for a static m
37bd0 75 74 65 78 2e 20 20 5e 48 6f 77 65 76 65 72 20  utex.  ^However 
37be0 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d 61  xMutexAlloc() ma
37bf0 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a 20  y use SQLite.** 
37c00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
37c10 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f 72 20  n for a fast or 
37c20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 2e  recursive mutex.
37c30 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
37c40 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 78  ill invoke the x
37c50 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74 68 6f  MutexEnd() metho
37c60 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
37c70 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a 2a  shutdown()] is.*
37c80 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f 6e  * called, but on
37c90 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f 72 20  ly if the prior 
37ca0 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49 6e  call to xMutexIn
37cb0 69 74 20 72 65 74 75 72 6e 65 64 20 53 51 4c 49  it returned SQLI
37cc0 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d 75  TE_OK..** If xMu
37cd0 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20 69 6e  texInit fails in
37ce0 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69 73 20   any way, it is 
37cf0 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c 65 61  expected to clea
37d00 6e 20 75 70 20 61 66 74 65 72 20 69 74 73 65 6c  n up after itsel
37d10 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72 65  f.** prior to re
37d20 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70 65  turning..*/.type
37d30 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
37d40 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
37d50 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
37d60 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
37d70 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
37d80 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a 78  hods {.  int (*x
37d90 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64 29  MutexInit)(void)
37da0 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
37db0 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73 71  End)(void);.  sq
37dc0 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a 78  lite3_mutex *(*x
37dd0 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74 29  MutexAlloc)(int)
37de0 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74 65  ;.  void (*xMute
37df0 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f 6d  xFree)(sqlite3_m
37e00 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20  utex *);.  void 
37e10 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28 73  (*xMutexEnter)(s
37e20 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b  qlite3_mutex *);
37e30 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 54  .  int (*xMutexT
37e40 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ry)(sqlite3_mute
37e50 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  x *);.  void (*x
37e60 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c 69  MutexLeave)(sqli
37e70 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20 20  te3_mutex *);.  
37e80 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c 64  int (*xMutexHeld
37e90 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  )(sqlite3_mutex 
37ea0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74  *);.  int (*xMut
37eb0 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69 74  exNotheld)(sqlit
37ec0 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b 0a  e3_mutex *);.};.
37ed0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37ee0 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 61 74   Mutex Verificat
37ef0 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a  ion Routines.**.
37f00 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  ** The sqlite3_m
37f10 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64 20  utex_held() and 
37f20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f  sqlite3_mutex_no
37f30 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65 73  theld() routines
37f40 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64  .** are intended
37f50 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
37f60 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65  assert() stateme
37f70 6e 74 73 2e 20 20 5e 54 68 65 20 53 51 4c 69 74  nts.  ^The SQLit
37f80 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72 20  e core.** never 
37f90 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74 69  uses these routi
37fa0 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69 64  nes except insid
37fb0 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61 6e  e an assert() an
37fc0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  d applications.*
37fd0 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74 6f  * are advised to
37fe0 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61 64   follow the lead
37ff0 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20 5e   of the core.  ^
38000 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
38010 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65 73  only.** provides
38020 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
38030 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
38040 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20 63  nes when it is c
38050 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
38060 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55 47  the SQLITE_DEBUG
38070 20 66 6c 61 67 2e 20 20 5e 45 78 74 65 72 6e 61   flag.  ^Externa
38080 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e  l mutex implemen
38090 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20 6f  tations.** are o
380a0 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f 20  nly required to 
380b0 70 72 6f 76 69 64 65 20 74 68 65 73 65 20 72 6f  provide these ro
380c0 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54 45  utines if SQLITE
380d0 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65 66  _DEBUG is.** def
380e0 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45 42  ined and if NDEB
380f0 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e 65  UG is not define
38100 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
38110 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20  routines should 
38120 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20 74  return true if t
38130 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65 69  he mutex in thei
38140 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69 73  r argument.** is
38150 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65 6c   held or not hel
38160 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2c  d, respectively,
38170 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67 20   by the calling 
38180 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  thread..**.** ^T
38190 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
381a0 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72 65  n is not require
381b0 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76 65  d to provided ve
381c0 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65 0a  rsions of these.
381d0 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
381e0 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e 20   actually work. 
381f0 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  If the implement
38200 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 70  ation does not p
38210 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a 2a  rovide working.*
38220 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74 68  * versions of th
38230 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69 74  ese routines, it
38240 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73 74   should at least
38250 20 70 72 6f 76 69 64 65 20 73 74 75 62 73 20 74   provide stubs t
38260 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72 65  hat always.** re
38270 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68 61  turn true so tha
38280 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20 67  t one does not g
38290 65 74 20 73 70 75 72 69 6f 75 73 20 61 73 73 65  et spurious asse
382a0 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e 0a  rtion failures..
382b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 72  **.** ^If the ar
382c0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
382d0 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 69  3_mutex_held() i
382e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
382f0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f 75   then.** the rou
38300 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74 75  tine should retu
38310 72 6e 20 31 2e 20 20 20 54 68 69 73 20 73 65 65  rn 1.   This see
38320 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75 69  ms counter-intui
38330 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63 6c  tive since.** cl
38340 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78 20  early the mutex 
38350 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20 69  cannot be held i
38360 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  f it does not ex
38370 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a 2a  ist.  But the.**
38380 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65 20   the reason the 
38390 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20 65  mutex does not e
383a0 78 69 73 74 20 69 73 20 62 65 63 61 75 73 65 20  xist is because 
383b0 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f 74  the build is not
383c0 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78 65  .** using mutexe
383d0 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e 6f  s.  And we do no
383e0 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 65 72  t want the asser
383f0 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  t() containing t
38400 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  he.** call to sq
38410 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64  lite3_mutex_held
38420 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20 61  () to fail, so a
38430 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72 6e   non-zero return
38440 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72 6f   is.** the appro
38450 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f 20  priate thing to 
38460 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  do.  ^The sqlite
38470 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64 28  3_mutex_notheld(
38480 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 73  ).** interface s
38490 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75 72  hould also retur
384a0 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20 61  n 1 when given a
384b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
384c0 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42 55 47  /.#ifndef NDEBUG
384d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  .int sqlite3_mut
384e0 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33 5f  ex_held(sqlite3_
384f0 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71 6c  mutex*);.int sql
38500 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65  ite3_mutex_nothe
38510 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ld(sqlite3_mutex
38520 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  *);.#endif../*.*
38530 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65  * CAPI3REF: Mute
38540 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54 68  x Types.**.** Th
38550 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
38560 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72 66  _alloc()] interf
38570 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ace takes a sing
38580 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 77  le argument.** w
38590 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20 74  hich is one of t
385a0 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
385b0 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  stants..**.** Th
385c0 65 20 73 65 74 20 6f 66 20 73 74 61 74 69 63 20  e set of static 
385d0 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68 61 6e  mutexes may chan
385e0 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c 69  ge from one SQLi
385f0 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  te release to th
38600 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
38610 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f 76  ications that ov
38620 65 72 72 69 64 65 20 74 68 65 20 62 75 69 6c 74  erride the built
38630 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63 20  -in mutex logic 
38640 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65 70 61  must be.** prepa
38650 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64 61  red to accommoda
38660 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  te additional st
38670 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a 2f  atic mutexes..*/
38680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38690 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20 20 20  MUTEX_FAST      
386a0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
386b0 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45   SQLITE_MUTEX_RE
386c0 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 31  CURSIVE        1
386d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
386e0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
386f0 54 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e 65  TER    2.#define
38700 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
38710 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20 33  ATIC_MEM       3
38720 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c    /* sqlite3_mal
38730 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  loc() */.#define
38740 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54   SQLITE_MUTEX_ST
38750 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20 34  ATIC_MEM2      4
38760 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a 2f    /* NOT USED */
38770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38780 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f 50 45  MUTEX_STATIC_OPE
38790 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c  N      4  /* sql
387a0 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28 29 20  ite3BtreeOpen() 
387b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
387c0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 50  E_MUTEX_STATIC_P
387d0 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a 20 73  RNG      5  /* s
387e0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29 20  qlite3_random() 
387f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
38800 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c  E_MUTEX_STATIC_L
38810 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a 20 6c  RU       6  /* l
38820 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a  ru page list */.
38830 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
38840 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55 32  UTEX_STATIC_LRU2
38850 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72 75 20        7  /* lru 
38860 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f 2a  page list */../*
38870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
38880 74 72 69 65 76 65 20 74 68 65 20 6d 75 74 65 78  trieve the mutex
38890 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
388a0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  connection.**.**
388b0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
388c0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
388d0 65 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  er the [sqlite3_
3