/ Hex Artifact Content
Login

Artifact 0cc43a0fa5d26cd26d2609b84ecf094a159e9cb9:


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 64 65 73 69 72 65 64 4c 6f 63  , int desiredLoc
9720: 6b 2c 20 69 6e 74 20 2a 67 6f 74 4c 6f 63 6b 29  k, int *gotLock)
9730: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 43 6c  ;.  int (*xShmCl
9740: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 73 68 6d  ose)(sqlite3_shm
9750: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
9760: 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f  Delete)(sqlite3_
9770: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9780: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 69 6e 74 20   *zName);.  int 
9790: 28 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74  (*xRename)(sqlit
97a0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
97b0: 68 61 72 20 2a 7a 4f 6c 64 2c 20 63 6f 6e 73 74  har *zOld, const
97c0: 20 63 68 61 72 20 2a 7a 4e 65 77 2c 20 69 6e 74   char *zNew, int
97d0: 20 64 69 72 53 79 6e 63 29 3b 0a 20 20 69 6e 74   dirSync);.  int
97e0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
97f0: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
9800: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
9810: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
9820: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
9830: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
9840: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
9850: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
9860: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
9870: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
9880: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
9890: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
98a0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
98b0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
98c0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
98d0: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
98e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
98f0: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
9900: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
9910: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
9920: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
9930: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
9940: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
9950: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
9960: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
9970: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
9980: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
9990: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
99a0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
99b0: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
99c0: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
99d0: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
99e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
99f0: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
9a00: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
9a10: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
9a20: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
9a30: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
9a40: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
9a50: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
9a60: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
9a70: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
9a80: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
9a90: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2e 0a 2a   and writable..*
9aa0: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
9ab0: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
9ac0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
9ad0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
9ae0: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
9af0: 61 62 6c 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  able..*/.#define
9b00: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
9b10: 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69  XISTS    0.#defi
9b20: 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  ne SQLITE_ACCESS
9b30: 5f 52 45 41 44 57 52 49 54 45 20 31 0a 23 64 65  _READWRITE 1.#de
9b40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
9b50: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 0a 0a  SS_READ      2..
9b60: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9b70: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
9b80: 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
9b90: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
9ba0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
9bb0: 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
9bc0: 75 73 20 6c 6f 63 6b 69 6e 67 20 73 74 61 74 65  us locking state
9bd0: 73 20 74 68 61 74 0a 2a 2a 20 61 6e 20 73 71 6c  s that.** an sql
9be0: 69 74 65 33 5f 73 68 6d 20 6f 62 6a 65 63 74 20  ite3_shm object 
9bf0: 63 61 6e 20 62 65 20 69 6e 2e 20 20 54 68 65 20  can be in.  The 
9c00: 53 51 4c 49 54 45 5f 53 48 4d 5f 51 55 45 52 59  SQLITE_SHM_QUERY
9c10: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 69 73 20 6e   integer.** is n
9c20: 6f 74 20 61 20 76 61 6c 69 64 20 64 61 74 61 20  ot a valid data 
9c30: 2d 20 69 74 20 69 73 20 61 20 63 6f 6e 73 74 61  - it is a consta
9c40: 6e 74 20 70 61 73 74 65 64 20 74 6f 20 74 68 65  nt pasted to the
9c50: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 66 73   .** sqlite3_vfs
9c60: 2e 78 53 68 6d 4c 6f 63 6b 28 29 20 6d 65 74 68  .xShmLock() meth
9c70: 6f 64 20 66 6f 72 20 71 75 65 72 79 69 6e 67 20  od for querying 
9c80: 74 68 65 20 63 75 72 72 65 6e 74 20 6c 6f 63 6b  the current lock
9c90: 0a 2a 2a 20 73 74 61 74 65 2e 0a 2a 2f 0a 23 64  .** state..*/.#d
9ca0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
9cb0: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 30 0a  _UNLOCK       0.
9cc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
9cd0: 48 4d 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  HM_READ         
9ce0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
9cf0: 5f 53 48 4d 5f 52 45 41 44 5f 46 55 4c 4c 20 20  _SHM_READ_FULL  
9d00: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
9d10: 54 45 5f 53 48 4d 5f 57 52 49 54 45 20 20 20 20  TE_SHM_WRITE    
9d20: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
9d30: 4c 49 54 45 5f 53 48 4d 5f 50 45 4e 44 49 4e 47  LITE_SHM_PENDING
9d40: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
9d50: 53 51 4c 49 54 45 5f 53 48 4d 5f 43 48 45 43 4b  SQLITE_SHM_CHECK
9d60: 50 4f 49 4e 54 20 20 20 35 0a 23 64 65 66 69 6e  POINT   5.#defin
9d70: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 52 45 43  e SQLITE_SHM_REC
9d80: 4f 56 45 52 20 20 20 20 20 20 36 0a 23 64 65 66  OVER      6.#def
9d90: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 51  ine SQLITE_SHM_Q
9da0: 55 45 52 59 20 20 20 20 20 20 20 20 28 2d 31 29  UERY        (-1)
9db0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9dc0: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
9dd0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
9de0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
9df0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
9e00: 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69  routine initiali
9e10: 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74  zes the.** SQLit
9e20: 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65  e library.  ^The
9e30: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
9e40: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
9e50: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
9e60: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
9e70: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
9e80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
9e90: 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ze()..** These r
9ea0: 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69  outines are desi
9eb0: 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70  gned to aid in p
9ec0: 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
9ed0: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75  ation and.** shu
9ee0: 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65  tdown on embedde
9ef0: 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b  d systems.  Work
9f00: 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74  station applicat
9f10: 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ions using.** SQ
9f20: 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f  Lite normally do
9f30: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76   not need to inv
9f40: 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68  oke either of th
9f50: 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
9f60: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
9f70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
9f80: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
9f90: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
9fa0: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
9fb0: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
9fc0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
9fd0: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
9fe0: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
9ff0: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
a000: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
a010: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
a020: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
a030: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
a040: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
a050: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
a060: 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66  .  ^(Only an eff
a070: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
a080: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
a090: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
a0a0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
a0b0: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
a0c0: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
a0d0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
a0e0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
a0f0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73  e3_shutdown() is
a100: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
a110: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68  call if it is th
a120: 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20  e first.** call 
a130: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
a140: 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20  own() since the 
a150: 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  last sqlite3_ini
a160: 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e  tialize().  ^(On
a170: 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69  ly.** an effecti
a180: 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ve call to sqlit
a190: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f  e3_shutdown() do
a1a0: 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c  es any deinitial
a1b0: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20  ization..** All 
a1c0: 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c  other valid call
a1d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  s to sqlite3_shu
a1e0: 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d  tdown() are harm
a1f0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
a200: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
a210: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e  _initialize() in
a220: 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61  terface is threa
a230: 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74  dsafe, but sqlit
a240: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
a250: 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71   is not.  The sq
a260: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
a270: 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20   interface must 
a280: 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66  only be called f
a290: 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20  rom a.** single 
a2a0: 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65  thread.  All ope
a2b0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
a2c0: 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65  ections] must be
a2d0: 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a   closed and all.
a2e0: 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ** other SQLite 
a2f0: 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62  resources must b
a300: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72  e deallocated pr
a310: 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a  ior to invoking.
a320: 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ** sqlite3_shutd
a330: 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  own()..**.** Amo
a340: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
a350: 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   ^sqlite3_initia
a360: 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f  lize() will invo
a370: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
a380: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
a390: 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68  rly, ^sqlite3_sh
a3a0: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c  utdown().** will
a3b0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
a3c0: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
a3d0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
a3e0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
a3f0: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
a400: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
a410: 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d  ..** ^If for som
a420: 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65  e reason, sqlite
a430: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
a440: 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74  s unable to init
a450: 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69  ialize.** the li
a460: 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69  brary (perhaps i
a470: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  t is unable to a
a480: 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64  llocate a needed
a490: 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a   resource such.*
a4a0: 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74  * as a mutex) it
a4b0: 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72   returns an [err
a4c0: 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74  or code] other t
a4d0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  han [SQLITE_OK].
a4e0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
a4f0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
a500: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
a510: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
a520: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
a530: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
a540: 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
a550: 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
a560: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
a570: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
a580: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
a590: 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
a5a0: 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
a5b0: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
a5c0: 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
a5d0: 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
a5e0: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
a5f0: 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
a600: 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
a610: 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
a620: 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
a630: 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
a640: 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
a650: 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77  * already.  ^How
a660: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
a670: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
a680: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   the [SQLITE_OMI
a690: 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63  T_AUTOINIT].** c
a6a0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
a6b0: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
a6c0: 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
a6d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
a6e0: 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
a6f0: 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
a700: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
a710: 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
a720: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
a730: 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
a740: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
a750: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
a760: 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
a770: 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
a780: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
a790: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
a7a0: 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
a7b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
a7c0: 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
a7d0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
a7e0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
a7f0: 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
a800: 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
a810: 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
a820: 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
a830: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
a840: 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
a850: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
a860: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
a870: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
a880: 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65  TOINIT] might be
a890: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
a8a0: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
a8b0: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
a8c0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
a8d0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
a8e0: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
a8f0: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
a900: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
a910: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
a920: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
a930: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
a940: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
a950: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
a960: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
a970: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
a980: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
a990: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
a9a0: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
a9b0: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
a9c0: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
a9d0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
a9e0: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
a9f0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
aa00: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
aa10: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
aa20: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
aa30: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
aa40: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
aa50: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
aa60: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
aa70: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
aa80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
aa90: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
aaa0: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
aab0: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
aac0: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
aad0: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
aae0: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
aaf0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
ab00: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
ab10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ab20: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
ab30: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
ab40: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ab50: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
ab60: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
ab70: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
ab80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
ab90: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
aba0: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
abb0: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
abc0: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
abd0: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
abe0: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
abf0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
ac00: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ac10: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
ac20: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
ac30: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
ac40: 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73  or Unix, Windows
ac50: 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68  , or OS/2..** Wh
ac60: 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64  en [custom build
ac70: 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  s | built for ot
ac80: 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a  her platforms].*
ac90: 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51  * (using the [SQ
aca0: 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d  LITE_OS_OTHER=1]
acb0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
acc0: 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
acd0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
ace0: 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
acf0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
ad00: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
ad10: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
ad20: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
ad30: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
ad40: 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
ad50: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
ad60: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
ad70: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ad80: 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
ad90: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
ada0: 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65  success and some
adb0: 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f   other [error co
adc0: 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c  de] upon.** fail
add0: 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ure..*/.int sqli
ade0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76  te3_initialize(v
adf0: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
ae00: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
ae10: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
ae20: 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74  _init(void);.int
ae30: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ae40: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
ae50: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
ae60: 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
ae70: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
ae80: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
ae90: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
aea0: 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
aeb0: 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
aec0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
aed0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
aee0: 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
aef0: 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
af00: 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
af10: 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
af20: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
af30: 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
af40: 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
af50: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
af60: 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
af70: 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
af80: 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
af90: 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
afa0: 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
afb0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
afc0: 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
afd0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
afe0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
aff0: 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
b000: 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
b010: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
b020: 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
b030: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
b040: 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
b050: 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
b060: 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
b070: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
b080: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
b090: 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
b0a0: 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
b0b0: 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
b0c0: 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
b0d0: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
b0e0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
b0f0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
b100: 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
b110: 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
b120: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
b130: 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
b140: 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
b150: 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
b160: 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
b170: 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
b180: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
b190: 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
b1a0: 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
b1b0: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
b1c0: 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
b1d0: 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
b1e0: 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
b1f0: 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
b200: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
b210: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
b220: 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
b230: 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
b240: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
b250: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
b260: 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
b270: 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  er.** [SQLITE_CO
b280: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
b290: 44 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  D | configuratio
b2a0: 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
b2b0: 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
b2c0: 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
b2d0: 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
b2e0: 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
b2f0: 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
b300: 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
b310: 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c 49 54 45  g on the [SQLITE
b320: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
b330: 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61  READ | configura
b340: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
b350: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
b360: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
b370: 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
b380: 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
b390: 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
b3a0: 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
b3b0: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
b3c0: 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
b3d0: 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
b3e0: 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
b3f0: 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
b400: 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
b410: 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
b420: 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
b430: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
b440: 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
b450: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
b460: 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
b470: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
b480: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  s.**.** The sqli
b490: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
b4a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
b4b0: 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
b4c0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
b4d0: 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
b4e0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
b4f0: 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
b500: 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
b510: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
b520: 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
b530: 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
b540: 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
b550: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
b560: 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
b570: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
b580: 75 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20  ument).  The.** 
b590: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
b5a0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68  g() interface sh
b5b0: 6f 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73 65  ould only be use
b5c0: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66  d immediately af
b5d0: 74 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ter.** the datab
b5e0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
b5f0: 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  s created using 
b600: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
b610: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ,.** [sqlite3_op
b620: 65 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c  en16()], or [sql
b630: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
b640: 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63    .**.** The sec
b650: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
b660: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
b670: 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
b680: 68 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  he.** configurat
b690: 69 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e  ion verb - an in
b6a0: 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
b6b0: 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a  indicates what.*
b6c0: 2a 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  * aspect of the 
b6d0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
b6e0: 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
b6f0: 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68  onfigured..** Th
b700: 65 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f  e only choice fo
b710: 72 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20  r this value is 
b720: 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
b730: 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20  _LOOKASIDE]..** 
b740: 4e 65 77 20 76 65 72 62 73 20 61 72 65 20 6c 69  New verbs are li
b750: 6b 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64  kely to be added
b760: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
b770: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
b780: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  * Additional arg
b790: 75 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e  uments depend on
b7a0: 20 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a   the verb..**.**
b7b0: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
b7c0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
b7d0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
b7e0: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
b7f0: 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
b800: 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
b810: 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
b820: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
b830: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
b840: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
b850: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
b860: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
b870: 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
b880: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
b890: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
b8a0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
b8b0: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
b8c0: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
b8d0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
b8e0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
b8f0: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
b900: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
b910: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
b920: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
b930: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
b940: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
b950: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
b960: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
b970: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
b980: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
b990: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
b9a0: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
b9b0: 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
b9c0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
b9d0: 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
b9e0: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
b9f0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
ba00: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
ba10: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
ba20: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
ba30: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
ba40: 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
ba50: 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
ba60: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
ba70: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
ba80: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
ba90: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
baa0: 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
bab0: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
bac0: 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
bad0: 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
bae0: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
baf0: 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
bb00: 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
bb10: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
bb20: 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
bb30: 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
bb40: 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
bb50: 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
bb60: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
bb70: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
bb80: 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
bb90: 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
bba0: 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
bbb0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
bbc0: 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
bbd0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
bbe0: 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
bbf0: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
bc00: 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
bc10: 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
bc20: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
bc30: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
bc40: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
bc50: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
bc60: 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
bc70: 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
bc80: 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
bc90: 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
bca0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
bcb0: 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
bcc0: 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
bcd0: 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
bce0: 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20  The xMalloc and 
bcf0: 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
bd00: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
bd10: 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  .** malloc() and
bd20: 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
bd30: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
bd40: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
bd50: 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d  * The xRealloc m
bd60: 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20  ethod must work 
bd70: 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20 66  like realloc() f
bd80: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
bd90: 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69   C library.** wi
bda0: 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e  th the exception
bdb0: 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65 63   that if the sec
bdc0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
bdd0: 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f  xRealloc is zero
bde0: 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75  ,.** xRealloc mu
bdf0: 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20  st be a no-op - 
be00: 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72 66  it must not perf
be10: 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69  orm any allocati
be20: 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63  on or.** dealloc
be30: 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65 20  ation.  ^SQLite 
be40: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
be50: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
be60: 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
be70: 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
be80: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
be90: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
bea0: 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e   xRoundup..** An
beb0: 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77 68  d so in cases wh
bec0: 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c 77  ere xRoundup alw
bed0: 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ays returns a po
bee0: 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a  sitive number,.*
bef0: 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70  * xRealloc can p
bf00: 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20 61  erform exactly a
bf10: 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c  s the standard l
bf20: 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28 29  ibrary realloc()
bf30: 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65   and.** still be
bf40: 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77   in compliance w
bf50: 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66 69  ith this specifi
bf60: 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53  cation..**.** xS
bf70: 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
bf80: 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
bf90: 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
bfa0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
bfb0: 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
bfc0: 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
bfd0: 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
bfe0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
bff0: 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
c000: 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
c010: 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
c020: 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
c030: 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
c040: 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
c050: 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
c060: 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
c070: 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
c080: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
c090: 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
c0a0: 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
c0b0: 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
c0c0: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
c0d0: 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
c0e0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
c0f0: 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
c100: 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
c110: 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
c120: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
c130: 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
c140: 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
c150: 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
c160: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c170: 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
c180: 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
c190: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
c1a0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
c1b0: 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
c1c0: 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
c1d0: 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
c1e0: 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
c1f0: 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
c200: 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
c210: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
c220: 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
c230: 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
c240: 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
c250: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28  ry allocator.  (
c260: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
c270: 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
c280: 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
c290: 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
c2a0: 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
c2b0: 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
c2c0: 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
c2d0: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
c2e0: 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
c2f0: 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
c300: 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
c310: 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
c320: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
c330: 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
c340: 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
c350: 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
c360: 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
c370: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
c380: 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
c390: 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
c3a0: 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
c3b0: 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
c3c0: 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
c3d0: 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
c3e0: 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
c3f0: 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
c400: 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
c410: 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
c420: 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
c430: 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
c440: 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
c450: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
c460: 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
c470: 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
c480: 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
c490: 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
c4a0: 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
c4b0: 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
c4c0: 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
c4d0: 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
c4e0: 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
c4f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
c500: 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
c510: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
c520: 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
c530: 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
c540: 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
c550: 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
c560: 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
c570: 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
c580: 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
c590: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
c5a0: 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
c5b0: 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
c5c0: 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
c5d0: 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
c5e0: 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
c5f0: 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
c600: 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
c610: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
c620: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
c630: 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
c640: 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
c650: 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
c660: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
c670: 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
c680: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
c690: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
c6a0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
c6b0: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
c6c0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
c6d0: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
c6e0: 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
c6f0: 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
c700: 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
c710: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
c720: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
c730: 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
c740: 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
c750: 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
c760: 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
c770: 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
c780: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
c790: 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
c7a0: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
c7b0: 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
c7c0: 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
c7d0: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
c7e0: 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
c7f0: 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
c800: 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
c810: 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
c820: 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
c830: 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
c840: 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
c850: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
c860: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
c870: 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
c880: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
c890: 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
c8a0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
c8b0: 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
c8c0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
c8d0: 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
c8e0: 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
c8f0: 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
c900: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
c910: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
c920: 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
c930: 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
c940: 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
c950: 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
c960: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
c970: 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
c980: 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
c990: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
c9a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
c9b0: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
c9c0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
c9d0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
c9e0: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
c9f0: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
ca00: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
ca10: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
ca20: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
ca30: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
ca40: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
ca50: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
ca60: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
ca70: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
ca80: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
ca90: 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
caa0: 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
cab0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
cac0: 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
cad0: 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
cae0: 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
caf0: 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
cb00: 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
cb10: 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
cb20: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
cb30: 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
cb40: 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
cb50: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
cb60: 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
cb70: 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
cb80: 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
cb90: 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
cba0: 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
cbb0: 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
cbc0: 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69  ding mode] to Si
cbd0: 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e  ngle-thread.  In
cbe0: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
cbf0: 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
cc00: 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
cc10: 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
cc20: 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
cc30: 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
cc40: 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
cc50: 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c  hread.   ^If SQL
cc60: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
cc70: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
cc80: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
cc90: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
cca0: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
ccb0: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
ccc0: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
ccd0: 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74  ible to change t
cce0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
ccf0: 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66  de] from its def
cd00: 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  ault.** value of
cd10: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61   Single-thread a
cd20: 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nd so [sqlite3_c
cd30: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
cd40: 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  turn .** [SQLITE
cd50: 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
cd60: 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
cd70: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
cd80: 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75  HREAD.** configu
cd90: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
cda0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
cdb0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
cdc0: 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
cdd0: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
cde0: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
cdf0: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
ce00: 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
ce10: 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
ce20: 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
ce30: 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
ce40: 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
ce50: 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
ce60: 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
ce70: 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
ce80: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
ce90: 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
cea0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
ceb0: 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
cec0: 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
ced0: 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
cee0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
cef0: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
cf00: 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
cf10: 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
cf20: 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
cf30: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
cf40: 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
cf50: 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
cf60: 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
cf70: 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
cf80: 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
cf90: 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
cfa0: 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
cfb0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
cfc0: 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
cfd0: 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
cfe0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
cff0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
d000: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
d010: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
d020: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
d030: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
d040: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
d050: 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
d060: 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
d070: 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
d080: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d090: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
d0a0: 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
d0b0: 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
d0c0: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
d0d0: 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
d0e0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
d0f0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
d100: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
d110: 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
d120: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
d130: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
d140: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
d150: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
d160: 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
d170: 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61  g mode] to Seria
d180: 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20  lized. In other 
d190: 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69  words, this opti
d1a0: 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c  on enables.** al
d1b0: 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64  l mutexes includ
d1c0: 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76  ing the recursiv
d1d0: 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20  e.** mutexes on 
d1e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
d1f0: 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
d200: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
d210: 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68  bjects..** In th
d220: 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69  is mode (which i
d230: 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68  s the default wh
d240: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
d250: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53  piled with.** [S
d260: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
d270: 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20  =1]) the SQLite 
d280: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73  library will its
d290: 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63  elf serialize ac
d2a0: 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61  cess.** to [data
d2b0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
d2c0: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
d2d0: 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74  statements] so t
d2e0: 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  hat the.** appli
d2f0: 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74  cation is free t
d300: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b  o use the same [
d310: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d320: 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73  ion] or the.** s
d330: 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
d340: 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66  atement] in diff
d350: 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74  erent threads at
d360: 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
d370: 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  ** ^If SQLite is
d380: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
d390: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
d3a0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
d3b0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
d3c0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
d3d0: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
d3e0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
d3f0: 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c  o set the Serial
d400: 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
d410: 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
d420: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d430: 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
d440: 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
d450: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
d460: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
d470: 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67  ERIALIZED config
d480: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
d490: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
d4a0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
d4b0: 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
d4c0: 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
d4d0: 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
d4e0: 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
d4f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
d500: 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
d510: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
d520: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
d530: 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
d540: 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
d550: 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
d560: 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
d570: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
d580: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
d590: 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
d5a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
d5b0: 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
d5c0: 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
d5d0: 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
d5e0: 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
d5f0: 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
d600: 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
d610: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
d620: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
d630: 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
d640: 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
d650: 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
d660: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
d670: 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
d680: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
d690: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
d6a0: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
d6b0: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
d6c0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
d6d0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
d6e0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
d6f0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
d700: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
d710: 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
d720: 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
d730: 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
d740: 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
d750: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
d760: 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
d770: 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
d780: 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
d790: 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
d7a0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
d7b0: 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
d7c0: 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
d7d0: 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
d7e0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
d7f0: 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
d800: 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
d810: 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f   for example. </
d820: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
d830: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
d840: 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
d850: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
d860: 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
d870: 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
d880: 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
d890: 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
d8a0: 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
d8b0: 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
d8c0: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
d8d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
d8e0: 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  ** statistics. ^
d8f0: 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
d900: 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
d910: 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c  cs are disabled,
d920: 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69   the .** followi
d930: 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
d940: 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
d950: 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
d960: 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
d970: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
d980: 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
d990: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
d9a0: 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
d9b0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
d9c0: 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
d9d0: 69 74 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  it()].**   <li> 
d9e0: 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
d9f0: 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
da00: 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
da10: 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
da20: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
da30: 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
da40: 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
da50: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
da60: 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
da70: 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
da80: 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
da90: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
daa0: 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
dab0: 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
dac0: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
dad0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
dae0: 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  CRATCH</dt>.** <
daf0: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
db00: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
db10: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
db20: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
db30: 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72  n use for.** scr
db40: 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68  atch memory.  Th
db50: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
db60: 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e  guments:  A poin
db70: 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
db80: 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
db90: 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
dba0: 68 20 74 68 65 20 73 63 72 61 63 68 20 61 6c 6c  h the scrach all
dbb0: 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65  ocations will be
dbc0: 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73  .** drawn, the s
dbd0: 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61  ize of each scra
dbe0: 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28  tch allocation (
dbf0: 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20  sz),.** and the 
dc00: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
dc10: 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  f scratch alloca
dc20: 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20  tions (N).  The 
dc30: 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d  sz.** argument m
dc40: 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c  ust be a multipl
dc50: 65 20 6f 66 20 31 36 2e 20 54 68 65 20 73 7a 20  e of 16. The sz 
dc60: 70 61 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64  parameter should
dc70: 20 62 65 20 61 20 66 65 77 20 62 79 74 65 73 0a   be a few bytes.
dc80: 2a 2a 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  ** larger than t
dc90: 68 65 20 61 63 74 75 61 6c 20 73 63 72 61 74 63  he actual scratc
dca0: 68 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64  h space required
dcb0: 20 64 75 65 20 74 6f 20 69 6e 74 65 72 6e 61 6c   due to internal
dcc0: 20 6f 76 65 72 68 65 61 64 2e 0a 2a 2a 20 54 68   overhead..** Th
dcd0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
dce0: 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
dcf0: 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
dd00: 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
dd10: 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
dd20: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
dd30: 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
dd40: 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
dd50: 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68  than one scratch
dd60: 20 62 75 66 66 65 72 20 70 65 72 20 74 68 72 65   buffer per thre
dd70: 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f  ad.  So.** N sho
dd80: 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74 68  uld be set to th
dd90: 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d  e expected maxim
dda0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  um number of thr
ddb0: 65 61 64 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  eads.  ^SQLite w
ddc0: 69 6c 6c 0a 2a 2a 20 6e 65 76 65 72 20 72 65 71  ill.** never req
ddd0: 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62  uire a scratch b
dde0: 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
ddf0: 72 65 20 74 68 61 6e 20 36 20 74 69 6d 65 73 20  re than 6 times 
de00: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
de10: 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53  page size. ^If S
de20: 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
de30: 73 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 63 72  s additional scr
de40: 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
de50: 6e 64 20 0a 2a 2a 20 77 68 61 74 20 69 73 20 70  nd .** what is p
de60: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
de70: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
de80: 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
de90: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
dea0: 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
deb0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
dec0: 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
ded0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
dee0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
def0: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
df00: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
df10: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
df20: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
df30: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
df40: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
df50: 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
df60: 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
df70: 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
df80: 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a  lemenation.  .**
df90: 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
dfa0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  ion should not b
dfb0: 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70  e used if an app
dfc0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
dfd0: 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
dfe0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
dff0: 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
e000: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
e010: 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  CACHE option..**
e020: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
e030: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
e040: 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
e050: 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
e060: 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
e070: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
e080: 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
e090: 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
e0a0: 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
e0b0: 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
e0c0: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
e0d0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
e0e0: 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
e0f0: 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
e100: 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
e110: 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
e120: 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
e130: 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
e140: 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
e150: 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
e160: 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
e170: 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
e180: 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
e190: 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
e1a0: 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
e1b0: 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
e1c0: 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
e1d0: 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
e1e0: 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
e1f0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
e200: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
e210: 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
e220: 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
e230: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
e240: 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
e250: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
e260: 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
e270: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
e280: 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
e290: 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
e2a0: 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
e2b0: 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
e2c0: 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
e2d0: 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
e2e0: 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
e2f0: 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
e300: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
e310: 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
e320: 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
e330: 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
e340: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
e350: 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
e360: 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
e370: 2e 0a 2a 2a 20 5e 54 68 65 20 69 6d 70 6c 65 6d  ..** ^The implem
e380: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 75  entation might u
e390: 73 65 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  se one or more o
e3a0: 66 20 74 68 65 20 4e 20 62 75 66 66 65 72 73 20  f the N buffers 
e3b0: 74 6f 20 68 6f 6c 64 20 0a 2a 2a 20 6d 65 6d 6f  to hold .** memo
e3c0: 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 6e  ry accounting in
e3d0: 66 6f 72 6d 61 74 69 6f 6e 2e 20 54 68 65 20 70  formation. The p
e3e0: 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
e3f0: 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
e400: 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
e410: 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
e420: 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
e430: 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
e440: 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
e450: 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
e460: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
e470: 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
e480: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
e490: 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
e4a0: 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
e4b0: 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
e4c0: 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
e4d0: 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  * for all of its
e4e0: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
e4f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
e500: 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
e510: 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79  ovided.** for by
e520: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
e530: 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51  SCRATCH] and [SQ
e540: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
e550: 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65  CACHE]..** There
e560: 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
e570: 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20  ents: An 8-byte 
e580: 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
e590: 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
e5a0: 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
e5b0: 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
e5c0: 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
e5d0: 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
e5e0: 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
e5f0: 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
e600: 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
e610: 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
e620: 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
e630: 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
e640: 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
e650: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
e660: 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
e670: 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
e680: 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
e690: 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
e6a0: 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
e6b0: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
e6c0: 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
e6d0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
e6e0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
e6f0: 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
e700: 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
e710: 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
e720: 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
e730: 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
e740: 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
e750: 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
e760: 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
e770: 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
e780: 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
e790: 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
e7a0: 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
e7b0: 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
e7c0: 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
e7d0: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
e7e0: 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
e7f0: 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
e800: 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
e810: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
e820: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
e830: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
e840: 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
e850: 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
e860: 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
e870: 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
e880: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
e890: 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
e8a0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
e8b0: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
e8c0: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
e8d0: 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
e8e0: 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
e8f0: 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
e900: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
e910: 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
e920: 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
e930: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
e940: 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
e950: 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
e960: 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
e970: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
e980: 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
e990: 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
e9a0: 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
e9b0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e9c0: 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
e9d0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
e9e0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
e9f0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
ea00: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
ea10: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
ea20: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
ea30: 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
ea40: 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
ea50: 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
ea60: 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
ea70: 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
ea80: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
ea90: 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
eaa0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
eab0: 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
eac0: 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
ead0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
eae0: 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
eaf0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
eb00: 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
eb10: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
eb20: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
eb30: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
eb40: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
eb50: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
eb60: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
eb70: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
eb80: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
eb90: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
eba0: 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
ebb0: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
ebc0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
ebd0: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
ebe0: 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
ebf0: 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
ec00: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
ec10: 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
ec20: 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
ec30: 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
ec40: 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
ec50: 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
ec60: 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
ec70: 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
ec80: 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
ec90: 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
eca0: 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
ecb0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
ecc0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
ecd0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
ece0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
ecf0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
ed00: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
ed10: 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
ed20: 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
ed30: 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
ed40: 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
ed50: 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
ed60: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
ed70: 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
ed80: 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
ed90: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
eda0: 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
edb0: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
edc0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
edd0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
ede0: 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
edf0: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
ee00: 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
ee10: 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
ee20: 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c  rmine the defaul
ee30: 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t.** memory allo
ee40: 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c  cation for the l
ee50: 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
ee60: 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63  allocator on eac
ee70: 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
ee80: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
ee90: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
eea0: 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f  is the.** size o
eeb0: 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65  f each lookaside
eec0: 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64   buffer slot and
eed0: 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74   the second is t
eee0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
eef0: 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20  slots allocated 
ef00: 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
ef10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20   connection.)^  
ef20: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65  ^(This option se
ef30: 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66  ts the.** <i>def
ef40: 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
ef50: 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
ef60: 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
ef70: 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62  OKASIDE].** verb
ef80: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
ef90: 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
efa0: 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
efb0: 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
efc0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
efd0: 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
efe0: 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
eff0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
f000: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
f010: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
f020: 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
f030: 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
f040: 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
f050: 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
f060: 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
f070: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
f080: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
f090: 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
f0a0: 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
f0b0: 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
f0c0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
f0d0: 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
f0e0: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
f0f0: 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
f100: 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
f110: 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
f120: 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
f130: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
f140: 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f  NFIG_GETPCACHE</
f150: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
f160: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
f170: 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
f180: 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
f190: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
f1a0: 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
f1b0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
f1c0: 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
f1d0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
f1e0: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
f1f0: 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
f200: 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
f210: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
f220: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
f230: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
f240: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f250: 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
f260: 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
f270: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
f280: 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
f290: 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
f2a0: 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
f2b0: 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
f2c0: 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
f2d0: 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
f2e0: 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
f2f0: 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
f300: 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
f310: 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
f320: 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
f330: 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
f340: 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
f350: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
f360: 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
f370: 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
f380: 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
f390: 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
f3a0: 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
f3b0: 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
f3c0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
f3d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
f3e0: 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
f3f0: 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
f400: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
f410: 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
f420: 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
f430: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
f440: 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
f450: 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
f460: 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
f470: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
f480: 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
f490: 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
f4a0: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
f4b0: 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
f4c0: 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
f4d0: 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
f4e0: 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
f4f0: 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
f500: 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
f510: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
f520: 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
f530: 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
f540: 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
f550: 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
f560: 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
f570: 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
f580: 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
f590: 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
f5a0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
f5b0: 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
f5c0: 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
f5d0: 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
f5e0: 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
f5f0: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
f600: 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
f610: 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
f620: 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
f630: 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
f640: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
f650: 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
f660: 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
f670: 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
f680: 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
f690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f6a0: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
f6b0: 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
f6c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
f6d0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
f6e0: 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
f6f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f700: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
f710: 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
f720: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
f730: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
f740: 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
f750: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
f760: 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
f770: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
f780: 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
f790: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
f7a0: 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
f7b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
f7c0: 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
f7d0: 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
f7e0: 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
f7f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
f800: 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
f810: 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
f820: 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
f830: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f840: 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
f850: 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
f860: 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
f870: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f880: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
f890: 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
f8a0: 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
f8b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
f8c0: 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
f8d0: 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
f8e0: 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
f8f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
f900: 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
f910: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
f920: 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
f930: 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
f940: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
f950: 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
f960: 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
f970: 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
f980: 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
f990: 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
f9a0: 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
f9b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
f9c0: 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
f9d0: 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
f9e0: 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
f9f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
fa00: 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
fa10: 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  15  /* sqlite3_p
fa20: 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a  cache_methods* *
fa30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
fa40: 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
fa50: 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
fa60: 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a  c, void* */../*.
fa70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
fa80: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
fa90: 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
faa0: 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
fab0: 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
fac0: 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
fad0: 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
fae0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
faf0: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
fb00: 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
fb10: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
fb20: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
fb30: 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
fb40: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
fb50: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
fb60: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
fb70: 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
fb80: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
fb90: 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
fba0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
fbb0: 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
fbc0: 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
fbd0: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
fbe0: 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
fbf0: 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
fc00: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
fc10: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
fc20: 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
fc30: 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
fc40: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
fc50: 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
fc60: 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
fc70: 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
fc80: 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
fc90: 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
fca0: 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
fcb0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
fcc0: 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
fcd0: 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
fce0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
fcf0: 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
fd00: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
fd10: 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
fd20: 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
fd30: 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
fd40: 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
fd50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
fd60: 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
fd70: 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
fd80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
fd90: 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
fda0: 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
fdb0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
fdc0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
fdd0: 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
fde0: 74 65 72 20 74 6f 20 61 6e 20 6d 65 6d 6f 72 79  ter to an memory
fdf0: 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
fe00: 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
fe10: 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
fe20: 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
fe30: 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
fe40: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
fe50: 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
fe60: 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
fe70: 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
fe80: 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
fe90: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
fea0: 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
feb0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
fec0: 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
fed0: 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
fee0: 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
fef0: 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
ff00: 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
ff10: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
ff20: 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
ff30: 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
ff40: 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
ff50: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ff60: 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
ff70: 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
ff80: 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
ff90: 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
ffa0: 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
ffb0: 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
ffc0: 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
ffd0: 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
ffe0: 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
fff0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10000 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
10010 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
10020 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
10030 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
10040 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
10050 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
10060 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 0a  he next smaller.
10070 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  ** multiple of 8
10080 2e 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51  .  See also: [SQ
10090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
100a0 41 53 49 44 45 5d 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ASIDE]</dd>.**.*
100b0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
100c0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
100d0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
100e0 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69  1001  /* void* i
100f0 6e 74 20 69 6e 74 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  nt int */.../*.*
10100 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
10110 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
10120 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
10130 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
10140 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
10150 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
10160 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
10170 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
10180 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
10190 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
101a0 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
101b0 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
101c0 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
101d0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
101e0 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
101f0 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
10200 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10210 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
10220 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20  codes(sqlite3*, 
10230 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
10240 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73  ** CAPI3REF: Las
10250 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a  t Insert Rowid.*
10260 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
10270 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61   in an SQLite ta
10280 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71 75 65  ble has a unique
10290 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
102a0 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
102b0 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
102c0 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
102d0 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
102e0 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
102f0 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
10300 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
10310 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
10320 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
10330 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
10340 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
10350 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
10360 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
10370 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
10380 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
10390 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
103a0 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
103b0 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
103c0 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
103d0 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
103e0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
103f0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ne returns the [
10400 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f  rowid] of the mo
10410 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63  st recent.** suc
10420 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
10430 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
10440 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74  se from the [dat
10450 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10460 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
10470 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66  t argument.  ^If
10480 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b   no successful [
10490 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65  INSERT]s.** have
104a0 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
104b0 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20  n that database 
104c0 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f  connection, zero
104d0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
104e0 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
104f0 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
10500 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 74 68  in a trigger, th
10510 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  en the [rowid] o
10520 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
10530 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72 6e 65  * row is returne
10540 64 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  d by this routin
10550 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  e as long as the
10560 20 74 72 69 67 67 65 72 20 69 73 20 72 75 6e 6e   trigger is runn
10570 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
10580 20 74 68 65 20 74 72 69 67 67 65 72 20 74 65 72   the trigger ter
10590 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76 61 6c  minates, the val
105a0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
105b0 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72  his routine.** r
105c0 65 76 65 72 74 73 20 74 6f 20 74 68 65 20 6c 61  everts to the la
105d0 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72 74 65  st value inserte
105e0 64 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  d before the tri
105f0 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a  gger fired.)^.**
10600 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
10610 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
10620 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
10630 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
10640 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
10650 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
10660 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
10670 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
10680 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
10690 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
106a0 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
106b0 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
106c0 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
106d0 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
106e0 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
106f0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
10700 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
10710 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
10720 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
10730 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
10740 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
10750 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
10760 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
10770 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
10780 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
10790 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
107a0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
107b0 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
107c0 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
107d0 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
107e0 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
107f0 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
10800 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
10810 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
10820 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
10830 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
10840 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
10850 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
10860 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
10870 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
10880 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
10890 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
108a0 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
108b0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
108c0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
108d0 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
108e0 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
108f0 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
10900 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
10910 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
10920 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
10930 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
10940 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
10950 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
10960 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
10970 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
10980 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
10990 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
109a0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
109b0 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
109c0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
109d0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
109e0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
109f0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
10a00 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
10a10 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
10a20 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
10a30 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
10a40 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
10a50 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
10a60 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
10a70 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  owid]..*/.sqlite
10a80 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
10a90 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
10aa0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
10ab0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10ac0 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
10ad0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
10ae0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
10af0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
10b00 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
10b10 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
10b20 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
10b30 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
10b40 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
10b50 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
10b60 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
10b70 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
10b80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10b90 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
10ba0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
10bb0 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68  er..** ^(Only ch
10bc0 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
10bd0 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
10be0 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
10bf0 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
10c00 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
10c10 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
10c20 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
10c30 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
10c40 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b  ** triggers or [
10c50 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
10c60 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ons] are not cou
10c70 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a  nted.)^ Use the.
10c80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  ** [sqlite3_tota
10c90 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
10ca0 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68  ction to find th
10cb0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
10cc0 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63  f changes.** inc
10cd0 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
10ce0 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
10cf0 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65  s and foreign ke
10d00 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  y actions..**.**
10d10 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
10d20 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
10d30 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
10d40 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
10d50 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
10d60 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
10d70 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
10d80 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
10d90 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67  * ^(A "row chang
10da0 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
10db0 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
10dc0 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
10dd0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
10de0 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
10df0 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
10e00 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
10e10 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
10e20 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
10e30 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  of [REPLACE] con
10e40 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
10e50 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
10e60 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
10e70 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c  g, [DROP TABLE],
10e80 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
10e90 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
10ea0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
10eb0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
10ec0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  s.)^.**.** A "tr
10ed0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
10ee0 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
10ef0 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
10f00 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
10f10 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
10f20 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
10f30 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
10f40 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
10f50 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
10f60 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
10f70 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
10f80 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
10f90 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
10fa0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
10fb0 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
10fc0 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
10fd0 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
10fe0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
10ff0 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
11000 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
11010 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
11020 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
11030 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
11040 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
11050 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  ation..**.** ^Ca
11060 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
11070 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
11080 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
11090 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
110a0 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
110b0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
110c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
110d0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
110e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
110f0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
11100 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
11110 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
11120 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
11130 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
11140 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
11150 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
11160 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63  ** ^Thus, when c
11170 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
11180 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
11190 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
111a0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
111b0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
111c0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
111d0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
111e0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
111f0 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
11200 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e  he top level.  ^
11210 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79  (Within the body
11220 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
11230 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
11240 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
11250 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
11260 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
11270 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
11280 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
11290 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
112a0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
112b0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
112c0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
112d0 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
112e0 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
112f0 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
11300 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
11310 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
11320 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
11330 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
11340 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
11350 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
11360 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
11370 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
11380 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
11390 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
113a0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
113b0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
113c0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
113d0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
113e0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
113f0 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
11400 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
11410 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11420 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
11430 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
11440 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
11450 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
11460 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
11470 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
11480 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
11490 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
114a0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
114b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
114c0 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
114d0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
114e0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
114f0 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
11500 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
11510 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
11520 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
11530 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
11540 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
11550 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
11560 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
11570 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68   opened..** ^(Th
11580 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64  e count returned
11590 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
115a0 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c  l_changes() incl
115b0 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
115c0 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52  .** from all [CR
115d0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
115e0 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73  rigger] contexts
115f0 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64   and changes mad
11600 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  e by.** [foreign
11610 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48   key actions]. H
11620 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
11630 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
11640 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
11650 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
11660 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
11670 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
11680 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
11690 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b  processing, or [
116a0 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63  DROP TABLE] proc
116b0 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20  essing.  The.** 
116c0 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
116d0 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76  nclude rows of v
116e0 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61  iews that fire a
116f0 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
11700 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67  igger],.** thoug
11710 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44  h if the INSTEAD
11720 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65   OF trigger make
11730 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73  s changes of its
11740 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e   own, those chan
11750 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  ges .** are coun
11760 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73  ted.)^.** ^The s
11770 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
11780 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
11790 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67  counts the chang
117a0 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a  es as soon as.**
117b0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
117c0 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
117d0 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65  s completed (whe
117e0 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
117f0 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73  handle.** is pas
11800 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
11810 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
11820 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
11830 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
11840 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
11850 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
11860 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
11870 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
11880 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
11890 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
118a0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
118b0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
118c0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
118d0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
118e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
118f0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
11900 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
11910 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
11920 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
11930 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
11940 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
11950 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
11960 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
11970 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
11980 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
11990 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
119a0 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
119b0 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a  ning Query.**.**
119c0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
119d0 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
119e0 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
119f0 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
11a00 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
11a10 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
11a20 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
11a30 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
11a40 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
11a50 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
11a60 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
11a70 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
11a80 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
11a90 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
11aa0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
11ab0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
11ac0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
11ad0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
11ae0 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
11af0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
11b00 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
11b10 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
11b20 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
11b30 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
11b40 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
11b50 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
11b60 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
11b70 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
11b80 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
11b90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11ba0 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
11bb0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
11bc0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
11bd0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
11be0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
11bf0 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
11c00 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
11c10 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
11c20 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
11c30 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
11c40 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
11c50 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
11c60 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
11c70 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
11c80 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
11c90 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
11ca0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
11cb0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
11cc0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
11cd0 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
11ce0 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
11cf0 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
11d00 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
11d10 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
11d20 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
11d30 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
11d40 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
11d50 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
11d60 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
11d70 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
11d80 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
11d90 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
11da0 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
11db0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
11dc0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
11dd0 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
11de0 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
11df0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
11e00 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
11e10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11e20 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
11e30 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
11e40 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
11e50 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
11e60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
11e70 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
11e80 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
11e90 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
11ea0 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
11eb0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
11ec0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
11ed0 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
11ee0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
11ef0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
11f00 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
11f10 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
11f20 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
11f30 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
11f40 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
11f50 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
11f60 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
11f70 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
11f80 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
11f90 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
11fa0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
11fb0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
11fc0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
11fd0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
11fe0 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
11ff0 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
12000 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
12010 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
12020 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
12030 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
12040 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
12050 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
12060 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
12070 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
12080 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
12090 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
120a0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
120b0 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
120c0 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
120d0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
120e0 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
120f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
12100 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
12110 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
12120 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
12130 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
12140 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
12150 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
12160 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
12170 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
12180 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
12190 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
121a0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
121b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
121c0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
121d0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
121e0 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
121f0 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
12200 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
12210 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
12220 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
12230 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
12240 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
12250 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
12260 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
12270 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
12280 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
12290 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
122a0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
122b0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
122c0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
122d0 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
122e0 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
122f0 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
12300 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
12310 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
12320 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
12330 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
12340 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
12350 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
12360 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
12370 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
12380 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
12390 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
123a0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
123b0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
123c0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
123d0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
123e0 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
123f0 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
12400 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
12410 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
12420 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
12430 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
12440 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
12450 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
12460 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
12470 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
12480 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
12490 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
124a0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
124b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
124c0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
124d0 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
124e0 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
124f0 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
12500 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
12510 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
12520 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
12530 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
12540 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
12550 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12560 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
12570 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
12580 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
12590 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
125a0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
125b0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
125c0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
125d0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
125e0 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
125f0 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
12600 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
12610 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
12620 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
12630 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
12640 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
12650 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
12660 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
12670 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
12680 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
12690 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
126a0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
126b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
126c0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
126d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
126e0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
126f0 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
12700 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
12710 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
12720 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
12730 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
12740 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
12750 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
12760 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
12770 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
12780 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
12790 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
127a0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
127b0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
127c0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
127d0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
127e0 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
127f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
12800 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
12810 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
12820 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
12830 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
12840 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
12850 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
12860 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
12870 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
12880 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
12890 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
128a0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
128b0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
128c0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
128d0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
128e0 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
128f0 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
12900 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
12910 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
12920 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
12930 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
12940 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
12950 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
12960 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
12970 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
12980 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
12990 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
129a0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
129b0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
129c0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
129d0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
129e0 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
129f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
12a00 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
12a10 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
12a20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
12a30 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
12a40 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
12a50 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
12a60 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
12a70 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
12a80 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
12a90 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
12aa0 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
12ab0 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
12ac0 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
12ad0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
12ae0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
12af0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
12b00 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
12b10 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
12b20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
12b30 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
12b40 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
12b50 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  ** is made to op
12b60 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
12b70 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
12b80 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
12b90 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
12ba0 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
12bb0 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
12bc0 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
12bd0 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
12be0 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
12bf0 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
12c00 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
12c10 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
12c20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
12c30 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
12c40 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
12c50 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
12c60 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
12c70 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
12c80 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  Y].** or [SQLITE
12c90 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
12ca0 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
12cb0 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
12cc0 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
12cd0 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
12ce0 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
12cf0 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
12d00 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
12d10 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
12d20 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
12d30 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
12d40 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
12d50 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
12d60 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
12d70 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
12d80 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
12d90 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
12da0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
12db0 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
12dc0 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
12dd0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
12de0 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
12df0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
12e00 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
12e10 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
12e20 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
12e30 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
12e40 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
12e50 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
12e60 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
12e70 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
12e80 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
12e90 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
12ea0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
12eb0 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
12ec0 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
12ed0 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
12ee0 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
12ef0 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
12f00 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
12f10 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
12f20 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
12f30 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
12f40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
12f50 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
12f60 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
12f70 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42  * ^The [SQLITE_B
12f80 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f  USY] error is co
12f90 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49  nverted to [SQLI
12fa0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
12fb0 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  ].** when SQLite
12fc0 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c   is in the middl
12fd0 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61  e of a large tra
12fe0 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61  nsaction where a
12ff0 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65  ll the.** change
13000 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69  s will not fit i
13010 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  nto the in-memor
13020 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65  y cache.  SQLite
13030 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79   will.** already
13040 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44   hold a RESERVED
13050 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74   lock on the dat
13060 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20  abase file, but 
13070 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70  it needs.** to p
13080 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b  romote this lock
13090 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f   to EXCLUSIVE so
130a0 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69   that it can spi
130b0 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65  ll cache.** page
130c0 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  s into the datab
130d0 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74  ase file without
130e0 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72   harm to concurr
130f0 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20  ent.** readers. 
13100 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c   ^If it is unabl
13110 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
13120 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
13130 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
13140 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
13150 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
13160 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
13170 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
13180 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
13190 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
131a0 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
131b0 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
131c0 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
131d0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
131e0 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f  ED].  ^This erro
131f0 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
13200 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
13210 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
13220 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
13230 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
13240 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77  href="/cvstrac/w
13250 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
13260 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
13270 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
13280 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
13290 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
132a0 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
132b0 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
132c0 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
132d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
132e0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
132f0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
13300 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
13310 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
13320 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
13330 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
13340 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
13350 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
13360 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
13370 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
13380 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
13390 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
133a0 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
133b0 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20   clear the busy 
133c0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
133d0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
133e0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
133f0 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
13400 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
13410 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13420 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
13430 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
13440 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  er.  Any such ac
13450 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
13460 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
13470 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
13480 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
13490 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
134a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
134b0 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
134c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
134d0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
134e0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
134f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
13500 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
13510 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
13520 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
13530 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13540 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
13550 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ut.**.** ^This r
13560 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
13570 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
13580 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
13590 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
135a0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
135b0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
135c0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
135d0 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
135e0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
135f0 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
13600 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
13610 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
13620 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
13630 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
13640 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
13650 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
13660 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
13670 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
13680 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
13690 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
136a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
136b0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
136c0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
136d0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
136e0 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  D]..**.** ^Calli
136f0 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
13700 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
13710 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
13720 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
13730 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
13740 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
13750 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
13760 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
13770 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
13780 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
13790 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
137a0 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
137b0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
137c0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
137d0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
137e0 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
137f0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
13800 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
13810 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
13820 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
13830 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
13840 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f  is cleared.)^.*/
13850 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
13860 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
13870 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
13880 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
13890 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
138a0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
138b0 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 44 65 66  ueries.**.** Def
138c0 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
138d0 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
138e0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
138f0 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
13900 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
13910 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
13920 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
13930 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
13940 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
13950 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
13960 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
13970 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
13980 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
13990 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
139a0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
139b0 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
139c0 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
139d0 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
139e0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
139f0 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
13a00 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
13a10 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
13a20 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
13a30 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
13a40 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
13a50 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
13a60 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
13a70 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
13a80 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
13a90 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
13aa0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
13ab0 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
13ac0 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
13ad0 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
13ae0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
13af0 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
13b00 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
13b10 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
13b20 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
13b30 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
13b40 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
13b50 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
13b60 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
13b70 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
13b80 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
13b90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
13ba0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
13bb0 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
13bc0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
13bd0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
13be0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
13bf0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
13c00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
13c10 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
13c20 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
13c30 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
13c40 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
13c50 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
13c60 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
13c70 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
13c80 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
13c90 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
13ca0 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
13cb0 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
13cc0 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
13cd0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
13ce0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 73  ble()]..**.** As
13cf0 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74   an example of t
13d00 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
13d10 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20  format, suppose 
13d20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a  a query result.*
13d30 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  * is as follows:
13d40 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
13d50 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
13d60 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c     Name        |
13d70 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 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 2d 0a 2a 2a 20 20 20 20 20 20 20  ------.**       
13da0 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34   Alice       | 4
13db0 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20  3.**        Bob 
13dc0 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20          | 28.** 
13dd0 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20         Cindy    
13de0 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65     | 21.** </pre
13df0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
13e00 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  *.** There are t
13e10 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29  wo column (M==2)
13e20 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20   and three rows 
13e30 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68  (N==3).  Thus th
13e40 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c  e.** result tabl
13e50 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e  e has 8 entries.
13e60 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65    Suppose the re
13e70 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74  sult table is st
13e80 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72  ored.** in an ar
13e90 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75  ray names azResu
13ea0 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75  lt.  Then azResu
13eb0 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f  lt holds this co
13ec0 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntent:.**.** <bl
13ed0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
13ee0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
13ef0 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65  t&#91;0] = "Name
13f00 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
13f10 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22  esult&#91;1] = "
13f20 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Age";.**        
13f30 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20  azResult&#91;2] 
13f40 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20  = "Alice";.**   
13f50 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
13f60 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20  1;3] = "43";.** 
13f70 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
13f80 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a  #91;4] = "Bob";.
13f90 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
13fa0 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22  lt&#91;5] = "28"
13fb0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
13fc0 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43  sult&#91;6] = "C
13fd0 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20  indy";.**       
13fe0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d   azResult&#91;7]
13ff0 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72   = "21";.** </pr
14000 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
14010 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
14020 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
14030 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
14040 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
14050 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
14060 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
14070 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
14080 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
14090 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
140a0 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
140b0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
140c0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
140d0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
140e0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
140f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
14100 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
14110 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
14120 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
14130 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
14140 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
14150 74 20 73 68 6f 75 6c 64 20 70 61 73 73 20 74 68  t should pass th
14160 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70  e result table p
14170 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
14180 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69  3_free_table() i
14190 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65  n order to.** re
141a0 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
141b0 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63   that was malloc
141c0 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20  ed.  Because of 
141d0 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b  the way the.** [
141e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
141f0 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e  ] happens within
14200 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
14210 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e  le(), the callin
14220 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  g.** function mu
14230 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61  st not try to ca
14240 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ll [sqlite3_free
14250 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f  ()] directly.  O
14260 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nly.** [sqlite3_
14270 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73  free_table()] is
14280 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65   able to release
14290 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70   the memory prop
142a0 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e  erly and safely.
142b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
142c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
142d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
142e0 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
142f0 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
14300 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
14310 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
14320 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
14330 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
14340 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
14350 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
14360 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
14370 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
14380 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
14390 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
143a0 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
143b0 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
143c0 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
143d0 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
143e0 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
143f0 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
14400 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
14410 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
14420 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
14430 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
14440 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
14450 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
14460 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 29  ite3_errmsg()].)
14470 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ^.*/.int sqlite3
14480 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
14490 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
144a0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
144b0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
144c0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
144d0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
144e0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
144f0 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
14500 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
14510 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
14520 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
14530 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
14540 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
14550 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
14560 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
14570 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
14580 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
14590 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
145a0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
145b0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
145c0 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
145d0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
145e0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
145f0 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
14600 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
14610 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
14620 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
14630 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
14640 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
14650 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
14660 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
14670 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
14680 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
14690 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
146a0 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ary..**.** ^The 
146b0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
146c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
146d0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
146e0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
146f0 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
14700 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
14710 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
14720 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
14730 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
14740 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
14750 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
14760 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
14770 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
14780 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
14790 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
147a0 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
147b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
147c0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
147d0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
147e0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
147f0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
14800 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73  ng..**.** ^(In s
14810 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
14820 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
14830 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
14840 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
14850 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
14860 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
14870 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
14880 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
14890 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
148a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
148b0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
148c0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
148d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
148e0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
148f0 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
14900 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
14910 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
14920 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
14930 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
14940 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
14950 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
14960 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
14970 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
14980 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
14990 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
149a0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
149b0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
149c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
149d0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
149e0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
149f0 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
14a00 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
14a10 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
14a20 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
14a30 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
14a40 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
14a50 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
14a60 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
14a70 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
14a80 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
14a90 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
14aa0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
14ab0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
14ac0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
14ad0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
14ae0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
14af0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
14b00 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
14b10 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
14b20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
14b30 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
14b40 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
14b50 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
14b60 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
14b70 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
14b80 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
14b90 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
14ba0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
14bb0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
14bc0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
14bd0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
14be0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
14bf0 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
14c00 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
14c10 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
14c20 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  cters..**.** The
14c30 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
14c40 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
14c50 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
14c60 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
14c70 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
14c80 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
14c90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
14ca0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
14cb0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
14cc0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
14cd0 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
14ce0 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
14cf0 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
14d00 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
14d10 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
14d20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
14d30 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
14d40 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
14d50 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
14d60 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
14d70 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
14d80 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
14d90 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
14da0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
14db0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
14dc0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
14dd0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
14de0 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
14df0 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
14e00 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
14e10 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
14e20 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
14e30 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
14e40 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
14e50 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
14e60 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
14e70 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
14e80 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
14e90 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
14ea0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
14eb0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
14ec0 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
14ed0 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
14ee0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
14ef0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
14f00 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
14f10 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
14f20 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
14f30 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
14f40 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
14f50 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
14f60 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
14f70 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
14f80 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
14f90 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
14fa0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
14fb0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
14fc0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
14fd0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
14fe0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
14ff0 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
15000 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
15010 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
15020 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
15030 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
15040 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
15050 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
15060 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
15070 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15080 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
15090 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
150a0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
150b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
150c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
150d0 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
150e0 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
150f0 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
15100 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
15110 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
15120 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
15130 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
15140 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
15150 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
15160 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
15170 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
15180 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
15190 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
151a0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
151b0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
151c0 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
151d0 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
151e0 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
151f0 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
15200 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
15210 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
15220 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
15230 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
15240 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
15250 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
15260 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
15270 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
15280 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
15290 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
152a0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
152b0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
152c0 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
152d0 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
152e0 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
152f0 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
15300 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
15310 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
15320 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
15330 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
15340 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
15350 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
15360 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
15370 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
15380 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
15390 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
153a0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
153b0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
153c0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
153d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
153e0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
153f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
15400 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
15410 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
15420 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
15430 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
15440 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
15450 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
15460 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
15470 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
15480 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
15490 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
154a0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
154b0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
154c0 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
154d0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
154e0 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
154f0 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
15500 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
15510 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
15520 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
15530 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
15540 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
15550 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
15560 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
15570 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
15580 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
15590 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
155a0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
155b0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
155c0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
155d0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
155e0 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
155f0 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
15600 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
15610 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
15620 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
15630 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
15640 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
15650 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
15660 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
15670 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
15680 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
15690 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
156a0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
156b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
156c0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
156d0 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
156e0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
156f0 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
15700 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
15710 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
15720 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
15730 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
15740 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
15750 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
15760 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
15770 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
15780 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
15790 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
157a0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
157b0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
157c0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
157d0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
157e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
157f0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
15800 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
15810 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
15820 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
15830 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
15840 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
15850 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
15860 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
15870 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
15880 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
15890 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
158a0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
158b0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
158c0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
158d0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
158e0 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
158f0 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
15900 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
15910 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
15920 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
15930 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
15940 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
15950 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
15960 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
15970 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
15980 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
15990 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
159a0 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
159b0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
159c0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
159d0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
159e0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
159f0 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
15a00 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
15a10 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
15a20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
15a30 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
15a40 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
15a50 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
15a60 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
15a70 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
15a80 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
15a90 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
15aa0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
15ab0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
15ac0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
15ad0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
15ae0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
15af0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
15b00 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  (The sqlite3_rea
15b10 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
15b20 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
15b30 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
15b40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15b50 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
15b60 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
15b70 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
15b80 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
15b90 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
15ba0 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
15bb0 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
15bc0 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e  * parameter.)^ ^
15bd0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
15be0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
15bf0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
15c00 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
15c10 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
15c20 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
15c30 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
15c40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
15c50 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
15c60 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
15c70 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
15c80 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  loc()..** ^If th
15c90 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
15ca0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
15cb0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
15cc0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
15cd0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
15ce0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
15cf0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
15d00 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
15d10 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68  P) where P is th
15d20 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
15d30 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
15d40 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69  lloc()..** ^sqli
15d50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
15d60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
15d70 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
15d80 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
15d90 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
15da0 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
15db0 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
15dc0 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
15dd0 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
15de0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
15df0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
15e00 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
15e10 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
15e20 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
15e30 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
15e40 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
15e50 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
15e60 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
15e70 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
15e80 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
15e90 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
15ea0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
15eb0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
15ec0 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
15ed0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
15ee0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
15ef0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
15f00 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
15f10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
15f20 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
15f30 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
15f40 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
15f50 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
15f60 75 6e 64 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 6e  undary..**.** In
15f70 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
15f80 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
15f90 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
15fa0 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
15fb0 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
15fc0 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
15fd0 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
15fe0 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
15ff0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
16000 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
16010 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
16020 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
16030 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
16040 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
16050 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
16060 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
16070 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
16080 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   The Windows OS 
16090 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
160a0 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79 73  calls.** the sys
160b0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
160c0 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
160d0 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
160e0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
160f0 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
16100 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
16110 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
16120 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
16130 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
16140 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
16150 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
16160 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
16170 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
16180 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65 63  errors are detec
16190 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
161a0 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62 61   are reported ba
161b0 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
161c0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
161d0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
161e0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
161f0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
16200 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
16210 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
16220 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
16230 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
16240 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
16250 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
16260 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
16270 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
16280 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
16290 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
162a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
162b0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
162c0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
162d0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
162e0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
162f0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
16300 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
16310 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
16320 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
16330 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
16340 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
16350 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
16360 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
16370 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
16380 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
16390 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
163a0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
163b0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  d*, int);.void s
163c0 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
163d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
163e0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
163f0 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
16400 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
16410 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
16420 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
16430 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
16440 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
16450 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
16460 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
16470 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
16480 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
16490 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
164a0 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
164b0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
164c0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
164d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
164e0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
164f0 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
16500 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
16510 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
16520 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
16530 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
16540 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
16550 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
16560 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
16570 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
16580 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
16590 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
165a0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
165b0 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
165c0 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
165d0 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
165e0 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
165f0 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
16600 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
16610 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
16620 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
16630 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
16640 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
16650 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
16660 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
16670 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
16680 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16690 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
166a0 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
166b0 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
166c0 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
166d0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
166e0 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
166f0 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
16700 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
16710 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
16720 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
16730 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
16740 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
16750 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
16760 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
16770 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
16780 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
16790 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
167a0 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
167b0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
167c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
167d0 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
167e0 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
167f0 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
16800 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
16810 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
16820 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
16830 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33  d(void);.sqlite3
16840 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
16850 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
16860 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
16870 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
16880 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
16890 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a  umber Generator.
168a0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e  **.** SQLite con
168b0 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61  tains a high-qua
168c0 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
168d0 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61  om number genera
168e0 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20  tor (PRNG) used 
168f0 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e  to.** select ran
16900 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57  dom [ROWID | ROW
16910 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74  IDs] when insert
16920 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
16930 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
16940 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
16950 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
16960 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20  ssible [ROWID]. 
16970 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73   The PRNG is als
16980 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68  o used for.** th
16990 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f  e build-in rando
169a0 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c  m() and randombl
169b0 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ob() SQL functio
169c0 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66  ns.  This interf
169d0 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70  ace allows.** ap
169e0 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
169f0 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
16a00 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
16a10 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  poses..**.** ^A 
16a20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
16a30 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
16a40 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
16a50 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
16a60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
16a70 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74  t time this rout
16a80 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  ine is invoked (
16a90 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c  either internall
16aa0 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61  y or by.** the a
16ab0 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20  pplication) the 
16ac0 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75  PRNG is seeded u
16ad0 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
16ae0 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
16af0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
16b00 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
16b10 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
16b20 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
16b30 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65  ^On all subseque
16b40 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
16b50 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
16b60 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
16b70 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
16b80 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
16b90 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
16ba0 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
16bb0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
16bc0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
16bd0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74  3_randomness(int
16be0 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f   N, void *P);../
16bf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
16c00 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68  ompile-Time Auth
16c10 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61  orization Callba
16c20 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  cks.**.** ^This 
16c30 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72  routine register
16c40 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20 63  s a authorizer c
16c50 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
16c60 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
16c70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16c80 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
16c90 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
16ca0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
16cb0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
16cc0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
16cd0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
16ce0 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
16cf0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
16d00 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
16d10 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
16d20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
16d30 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
16d40 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
16d50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
16d60 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v2()].  ^At va
16d70 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
16d80 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
16d90 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
16da0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
16db0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
16dc0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
16dd0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
16de0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
16df0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
16e00 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
16e10 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
16e20 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
16e30 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
16e40 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
16e50 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
16e60 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
16e70 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
16e80 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
16e90 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
16ea0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
16eb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
16ec0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
16ed0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
16ee0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
16ef0 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
16f00 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
16f10 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
16f20 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
16f30 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
16f40 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
16f50 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
16f60 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
16f70 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
16f80 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
16f90 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
16fa0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
16fb0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
16fc0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
16fd0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
16fe0 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
16ff0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
17000 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
17010 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
17020 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
17030 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
17040 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
17050 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
17060 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
17070 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
17080 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
17090 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
170a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
170b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
170c0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
170d0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
170e0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
170f0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
17100 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
17110 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
17120 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
17130 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
17140 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
17150 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
17160 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
17170 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
17180 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
17190 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
171a0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
171b0 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
171c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
171d0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
171e0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
171f0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
17200 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
17210 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
17220 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
17230 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
17240 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
17250 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
17260 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
17270 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
17280 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
17290 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
172a0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
172b0 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
172c0 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
172d0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
172e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
172f0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
17300 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
17310 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
17320 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
17330 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
17340 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
17350 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
17360 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
17370 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
17380 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
17390 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
173a0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
173b0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
173c0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
173d0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
173e0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
173f0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
17400 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
17410 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
17420 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
17430 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
17440 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
17450 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66   a table..** ^If
17460 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
17470 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
17480 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
17490 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
174a0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
174b0 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
174c0 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
174d0 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
174e0 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
174f0 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
17500 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
17510 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
17520 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
17530 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
17540 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
17550 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
17560 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
17570 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
17580 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
17590 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
175a0 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
175b0 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
175c0 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
175d0 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
175e0 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
175f0 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
17600 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
17610 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
17620 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
17630 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
17640 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
17650 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
17660 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
17670 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
17680 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
17690 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
176a0 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
176b0 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
176c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
176d0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
176e0 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
176f0 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
17700 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
17710 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
17720 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
17730 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
17740 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
17750 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
17760 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
17770 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
17780 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
17790 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
177a0 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
177b0 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
177c0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
177d0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
177e0 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
177f0 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
17800 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
17810 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
17820 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
17830 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
17840 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
17850 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
17860 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
17870 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
17880 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
17890 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
178a0 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
178b0 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
178c0 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
178d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
178e0 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
178f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17900 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
17910 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
17920 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
17930 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
17940 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
17950 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
17960 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
17970 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
17980 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
17990 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
179a0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
179b0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
179c0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
179d0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
179e0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
179f0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
17a00 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
17a10 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
17a20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
17a30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
17a40 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
17a50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
17a60 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
17a70 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
17a80 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
17a90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17aa0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
17ab0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
17ac0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
17ad0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
17ae0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
17af0 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
17b00 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
17b10 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
17b20 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
17b30 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
17b40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
17b50 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
17b60 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
17b70 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
17b80 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
17b90 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
17ba0 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
17bb0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
17bc0 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
17bd0 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
17be0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
17bf0 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
17c00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
17c10 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
17c20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
17c30 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
17c40 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
17c50 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
17c60 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
17c70 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
17c80 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
17c90 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
17ca0 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
17cb0 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
17cc0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
17cd0 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
17ce0 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
17cf0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
17d00 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
17d10 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
17d20 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
17d30 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ange..*/.int sql
17d40 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
17d50 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
17d60 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
17d70 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
17d80 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
17d90 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
17da0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
17db0 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
17dc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17dd0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
17de0 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
17df0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
17e00 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
17e10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17e20 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
17e30 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
17e40 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
17e50 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
17e60 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
17e70 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
17e80 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
17e90 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
17ea0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
17eb0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
17ec0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
17ed0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
17ee0 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
17ef0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
17f00 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
17f10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17f20 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
17f30 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
17f40 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
17f50 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
17f60 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
17f70 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
17f80 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
17f90 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
17fa0 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
17fb0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
17fc0 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
17fd0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
17fe0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
17ff0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
18000 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
18010 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
18020 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
18030 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
18040 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
18050 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
18060 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
18070 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
18080 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
18090 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
180a0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
180b0 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
180c0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
180d0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
180e0 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
180f0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
18100 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18110 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
18120 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
18130 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
18140 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
18150 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
18160 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
18170 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
18180 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
18190 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
181a0 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
181b0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
181c0 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
181d0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
181e0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
181f0 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
18200 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
18210 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
18220 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
18230 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
18240 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18250 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
18260 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
18270 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
18280 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
18290 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
182a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
182b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
182c0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
182d0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
182e0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
182f0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
18300 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
18310 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
18320 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
18330 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
18340 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
18350 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
18360 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l 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 2a 20 33 72 64 20  *********** 3rd 
183a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
183b0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
183c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
183d0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
183e0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
183f0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
18400 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
18410 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
18420 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
18430 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
18440 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
18450 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18460 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
18470 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
18480 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
18490 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
184a0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
184b0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
184c0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
184d0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
184e0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
184f0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
18500 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
18510 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
18520 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
18530 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
18540 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18550 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
18560 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
18570 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
18580 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18590 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
185a0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
185b0 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
185c0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
185d0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
185e0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
185f0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
18600 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
18610 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
18620 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18630 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18640 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
18650 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
18660 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
18670 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18680 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18690 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
186a0 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
186b0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
186c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
186d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
186e0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
186f0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
18700 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
18710 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18720 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18730 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
18740 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
18750 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
18760 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
18770 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18780 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
18790 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
187a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
187b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
187c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
187d0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
187e0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
187f0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
18800 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
18810 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18820 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
18830 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
18840 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
18850 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
18860 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
18870 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
18880 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
18890 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
188a0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
188b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
188c0 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
188d0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
188e0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
188f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
18900 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
18910 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
18920 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
18930 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
18940 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
18950 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
18960 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
18970 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
18980 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
18990 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
189a0 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
189b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
189c0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
189d0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
189e0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
189f0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
18a00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
18a10 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
18a20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
18a30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
18a40 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
18a50 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
18a60 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
18a70 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
18a80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
18a90 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
18aa0 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
18ab0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
18ac0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
18ad0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
18ae0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
18af0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
18b00 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
18b10 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
18b20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
18b30 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
18b40 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
18b50 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
18b60 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
18b70 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
18b80 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
18b90 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
18ba0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
18bb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
18bc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18bd0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
18be0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
18bf0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
18c00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
18c10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18c20 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
18c30 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
18c40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
18c50 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
18c60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18c70 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
18c80 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
18c90 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
18ca0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
18cb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18cc0 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
18cd0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
18ce0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
18cf0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
18d00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
18d10 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
18d20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
18d30 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
18d40 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
18d50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
18d60 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
18d70 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
18d80 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
18d90 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
18da0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
18db0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
18dc0 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
18dd0 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
18de0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
18df0 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
18e00 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
18e10 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
18e20 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
18e30 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
18e40 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
18e50 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
18e60 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
18e70 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
18e80 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
18e90 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
18ea0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
18eb0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
18ec0 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
18ed0 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
18ee0 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
18ef0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
18f00 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
18f10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
18f20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
18f30 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
18f40 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
18f50 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
18f60 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
18f70 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
18f80 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
18f90 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
18fa0 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
18fb0 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
18fc0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
18fd0 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
18fe0 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
18ff0 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
19000 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
19010 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
19020 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
19030 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
19040 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
19050 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
19060 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  .)^.**.** ^The c
19070 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19080 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
19090 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
190a0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
190b0 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
190c0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
190d0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
190e0 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
190f0 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
19100 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
19110 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
19120 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
19130 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
19140 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
19150 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2f 0a 76  ook to run..*/.v
19160 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
19170 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
19180 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
19190 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
191a0 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
191b0 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
191c0 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
191d0 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
191e0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
191f0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
19200 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
19210 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
19220 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
19230 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
19240 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ks.**.** ^This r
19250 6f 75 74 69 6e 65 20 63 6f 6e 66 69 67 75 72 65  outine configure
19260 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  s a callback fun
19270 63 74 69 6f 6e 20 2d 20 74 68 65 0a 2a 2a 20 70  ction - the.** p
19280 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
19290 20 2d 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b   - that is invok
192a0 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
192b0 64 75 72 69 6e 67 20 6c 6f 6e 67 0a 2a 2a 20 72  during long.** r
192c0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 20  unning calls to 
192d0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
192e0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
192f0 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
19300 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 2e  e3_get_table()].
19310 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
19320 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
19330 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
19340 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
19350 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
19360 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uery..**.** ^If 
19370 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
19380 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
19390 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
193a0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
193b0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
193c0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
193d0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
193e0 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
193f0 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
19400 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
19410 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
19420 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 75  gress handler mu
19430 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
19440 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
19450 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
19460 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
19470 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
19480 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
19490 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
194a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
194b0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
194c0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
194d0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
194e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
194f0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
19500 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
19510 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
19520 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73  ph..**.*/.void s
19530 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
19540 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
19550 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
19560 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
19570 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
19580 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
19590 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
195a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
195b0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
195c0 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
195d0 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
195e0 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
195f0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
19600 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
19610 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
19620 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
19630 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
19640 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
19650 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
19660 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
19670 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
19680 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
19690 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
196a0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
196b0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
196c0 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
196d0 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
196e0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
196f0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
19700 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
19710 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
19720 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
19730 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
19740 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
19750 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
19760 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
19770 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
19780 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
19790 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
197a0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
197b0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
197c0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
197d0 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
197e0 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
197f0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
19800 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
19810 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
19820 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
19830 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
19840 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
19850 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
19860 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
19870 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
19880 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
19890 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
198a0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
198b0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
198c0 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
198d0 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
198e0 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
198f0 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
19900 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
19910 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
19920 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
19930 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
19940 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
19950 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
19960 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
19970 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
19980 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
19990 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
199a0 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
199b0 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
199c0 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
199d0 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
199e0 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
199f0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
19a00 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
19a10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
19a20 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
19a30 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
19a40 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
19a50 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
19a60 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
19a70 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
19a80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
19a90 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
19aa0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
19ab0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
19ac0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
19ad0 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
19ae0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
19af0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
19b00 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
19b10 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
19b20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
19b30 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
19b40 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
19b50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
19b60 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
19b70 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
19b80 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
19b90 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
19ba0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
19bb0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
19bc0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
19bd0 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
19be0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
19bf0 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  CACHE],.** and/o
19c00 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  r [SQLITE_OPEN_P
19c10 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
19c20 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
19c30 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
19c40 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
19c50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
19c60 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
19c70 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
19c80 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
19c90 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
19ca0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
19cb0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
19cc0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
19cd0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
19ce0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
19cf0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
19d00 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
19d10 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
19d20 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
19d30 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
19d40 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
19d50 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
19d60 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
19d70 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
19d80 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
19d90 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
19da0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
19db0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
19dc0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
19dd0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
19de0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
19df0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
19e00 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
19e10 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
19e20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
19e30 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
19e40 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
19e50 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
19e60 63 72 65 61 74 65 73 20 69 74 20 69 66 0a 2a 2a  creates it if.**
19e70 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
19e80 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
19e90 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
19ea0 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
19eb0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
19ec0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
19ed0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
19ee0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
19ef0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
19f00 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
19f10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
19f20 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
19f30 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
19f40 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
19f50 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d  r one of the com
19f60 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20  binations shown 
19f70 61 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a  above combined.*
19f80 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
19f90 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
19fa0 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
19fb0 55 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53  ULLMUTEX],.** [S
19fc0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
19fd0 44 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b  DCACHE] and/or [
19fe0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
19ff0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a  EDCACHE] flags,.
1a000 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1a010 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1a020 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1a030 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1a040 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1a050 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
1a060 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a070 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
1a080 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
1a090 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
1a0a0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
1a0b0 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
1a0c0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
1a0d0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1a0e0 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1a0f0 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
1a100 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1a110 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
1a120 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
1a130 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a140 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
1a150 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1a160 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
1a170 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
1a180 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
1a190 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
1a1a0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1a1b0 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
1a1c0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
1a1d0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
1a1e0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1a1f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a200 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
1a210 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
1a220 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
1a230 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1a240 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
1a250 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
1a260 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
1a270 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1a280 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
1a290 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
1a2a0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1a2b0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1a2c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1a2d0 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
1a2e0 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
1a2f0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1a300 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
1a310 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
1a320 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
1a330 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
1a340 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1a350 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
1a360 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
1a370 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
1a380 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
1a390 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
1a3a0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
1a3b0 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
1a3c0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1a3d0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1a3e0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1a3f0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
1a400 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
1a410 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
1a420 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
1a430 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
1a440 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
1a450 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
1a460 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
1a470 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
1a480 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
1a490 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
1a4a0 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
1a4b0 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
1a4c0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
1a4d0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
1a4e0 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
1a4f0 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
1a500 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
1a510 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
1a520 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1a530 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1a540 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
1a550 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
1a560 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
1a570 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
1a580 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
1a590 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
1a5a0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
1a5b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1a5c0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1a5d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
1a5e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1a5f0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1a600 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
1a610 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
1a620 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1a630 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
1a640 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1a650 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
1a660 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
1a670 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a680 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
1a690 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
1a6a0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
1a6b0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1a6c0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1a6d0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1a6e0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1a6f0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
1a700 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
1a710 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
1a720 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
1a730 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
1a740 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1a750 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1a760 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
1a770 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
1a780 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
1a790 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
1a7a0 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
1a7b0 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
1a7c0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
1a7d0 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
1a7e0 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
1a7f0 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
1a800 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
1a810 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1a820 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1a830 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()..*/.int sqlit
1a840 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
1a850 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1a860 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1a870 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1a880 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1a890 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
1a8a0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1a8b0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
1a8c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
1a8d0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
1a8e0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1a8f0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1a900 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
1a910 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1a920 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1a930 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1a940 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1a950 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
1a960 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1a970 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1a980 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1a990 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1a9a0 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
1a9b0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1a9c0 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
1a9d0 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
1a9e0 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
1a9f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
1aa00 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
1aa10 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
1aa20 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
1aa30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
1aa40 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
1aa50 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sages.**.** ^The
1aa60 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1aa70 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
1aa80 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
1aa90 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
1aaa0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
1aab0 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
1aac0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1aad0 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
1aae0 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73   API call.** ass
1aaf0 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
1ab00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1ab10 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72  ion]. If a prior
1ab20 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
1ab30 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74  .** but the most
1ab40 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
1ab50 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
1ab60 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
1ab70 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72  m.** sqlite3_err
1ab80 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
1ab90 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ned.  ^The sqlit
1aba0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
1abb0 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
1abc0 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
1abd0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
1abe0 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
1abf0 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
1ac00 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
1ac10 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
1ac20 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
1ac30 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
1ac40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1ac50 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
1ac60 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
1ac70 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
1ac80 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
1ac90 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
1aca0 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
1acb0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
1acc0 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
1acd0 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
1ace0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
1acf0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
1ad00 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
1ad10 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
1ad20 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
1ad30 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
1ad40 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
1ad50 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
1ad60 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
1ad70 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
1ad80 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
1ad90 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
1ada0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
1adb0 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
1adc0 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
1add0 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57  tions.)^.**.** W
1ade0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
1adf0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
1ae00 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
1ae10 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
1ae20 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
1ae30 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
1ae40 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
1ae50 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
1ae60 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
1ae70 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
1ae80 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
1ae90 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
1aea0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
1aeb0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
1aec0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
1aed0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
1aee0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
1aef0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
1af00 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
1af10 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
1af20 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
1af30 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
1af40 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
1af50 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
1af60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1af70 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
1af80 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
1af90 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
1afa0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
1afb0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
1afc0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
1afd0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
1afe0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
1aff0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
1b000 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
1b010 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
1b020 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
1b030 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
1b040 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
1b050 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
1b060 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
1b070 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
1b080 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
1b090 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
1b0a0 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
1b0b0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
1b0c0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
1b0d0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
1b0e0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
1b0f0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
1b100 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1b110 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1b120 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
1b130 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1b140 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
1b150 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1b160 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
1b170 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
1b180 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
1b190 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
1b1a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b1b0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
1b1c0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
1b1d0 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
1b1e0 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
1b1f0 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
1b200 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
1b210 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
1b220 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
1b230 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1b240 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
1b250 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
1b260 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
1b270 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
1b280 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53  a.** "compiled S
1b290 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
1b2a0 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
1b2b0 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20  atement"..**.** 
1b2c0 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
1b2d0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
1b2e0 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
1b2f0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1b300 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
1b310 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
1b320 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1b330 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
1b340 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
1b350 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
1b360 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
1b370 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   [host parameter
1b380 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
1b390 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
1b3a0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
1b3b0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
1b3c0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
1b3d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1b3e0 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
1b3f0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
1b400 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
1b410 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b420 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
1b430 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
1b440 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
1b450 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
1b460 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
1b470 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
1b480 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1b490 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
1b4a0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
1b4b0 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
1b4c0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
1b4d0 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
1b4e0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
1b4f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
1b500 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1b510 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
1b520 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
1b530 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
1b540 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a  time Limits.**.*
1b550 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
1b560 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
1b570 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
1b580 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
1b590 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
1b5a0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
1b5b0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
1b5c0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1b5d0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
1b5e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b5f0 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
1b600 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
1b610 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
1b620 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b630 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
1b640 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
1b650 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
1b660 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
1b670 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
1b680 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
1b690 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
1b6a0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
1b6b0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
1b6c0 6e 73 74 72 75 63 74 2e 20 20 54 68 65 20 66 75  nstruct.  The fu
1b6d0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1b6e0 68 65 20 6f 6c 64 20 6c 69 6d 69 74 2e 29 5e 0a  he old limit.)^.
1b6f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65  **.** ^If the ne
1b700 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67  w limit is a neg
1b710 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68  ative number, th
1b720 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61  e limit is uncha
1b730 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 74  nged..** ^(For t
1b740 68 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  he limit categor
1b750 79 20 6f 66 20 53 51 4c 49 54 45 5f 4c 49 4d 49  y of SQLITE_LIMI
1b760 54 5f 58 59 5a 20 74 68 65 72 65 20 69 73 20 61  T_XYZ there is a
1b770 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
1b780 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
1b790 0a 2a 2a 20 73 65 74 20 62 79 20 61 20 63 6f 6d  .** set by a com
1b7a0 70 69 6c 65 2d 74 69 6d 65 20 43 20 70 72 65 70  pile-time C prep
1b7b0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 6e  rocessor macro n
1b7c0 61 6d 65 64 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  amed .** [limits
1b7d0 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 58 59   | SQLITE_MAX_XY
1b7e0 5a 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  Z]..** (The "_LI
1b7f0 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
1b800 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
1b810 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
1b820 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
1b830 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
1b840 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
1b850 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
1b860 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
1b870 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
1b880 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
1b890 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
1b8a0 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
1b8b0 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
1b8c0 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
1b8d0 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
1b8e0 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
1b8f0 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
1b900 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
1b910 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
1b920 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
1b930 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
1b940 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
1b950 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
1b960 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
1b970 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
1b980 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
1b990 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
1b9a0 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
1b9b0 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
1b9c0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
1b9d0 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
1b9e0 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
1b9f0 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
1ba00 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
1ba10 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
1ba20 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
1ba30 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
1ba40 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
1ba50 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
1ba60 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
1ba70 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
1ba80 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
1ba90 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
1baa0 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
1bab0 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
1bac0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
1bad0 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
1bae0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
1baf0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1bb00 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
1bb10 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
1bb20 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
1bb30 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
1bb40 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
1bb50 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
1bb60 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
1bb70 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
1bb80 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
1bb90 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1bba0 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
1bbb0 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
1bbc0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
1bbd0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
1bbe0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
1bbf0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
1bc00 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
1bc10 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
1bc20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1bc30 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
1bc40 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
1bc50 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
1bc60 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
1bc70 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
1bc80 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
1bc90 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
1bca0 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
1bcb0 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
1bcc0 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
1bcd0 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
1bce0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
1bcf0 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
1bd00 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
1bd10 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
1bd20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
1bd30 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
1bd40 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1bd50 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
1bd60 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
1bd70 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
1bd80 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
1bd90 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
1bda0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1bdb0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
1bdc0 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
1bdd0 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
1bde0 65 20 72 6f 77 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  e row.<dd>)^.**.
1bdf0 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1be00 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
1be10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1be20 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
1be30 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
1be40 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
1be50 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1be60 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
1be70 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
1be80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1be90 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
1bea0 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
1beb0 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
1bec0 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
1bed0 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
1bee0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1bef0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
1bf00 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
1bf10 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
1bf20 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
1bf30 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1bf40 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1bf50 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
1bf60 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1bf70 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
1bf80 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
1bf90 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
1bfa0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
1bfb0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1bfc0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
1bfd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1bfe0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1bff0 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
1c000 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
1c010 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
1c020 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1c030 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
1c040 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c050 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1c060 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
1c070 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
1c080 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
1c090 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
1c0a0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
1c0b0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
1c0c0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1c0d0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
1c0e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1c0f0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1c100 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
1c110 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
1c120 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1c130 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
1c140 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
1c150 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1c160 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
1c170 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
1c180 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
1c190 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1c1a0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
1c1b0 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
1c1c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1c1d0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
1c1e0 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
1c1f0 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
1c200 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
1c210 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
1c220 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1c230 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
1c240 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  UMBER</dt>.** <d
1c250 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
1c260 6d 62 65 72 20 6f 66 20 76 61 72 69 61 62 6c 65  mber of variable
1c270 73 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  s in an SQL stat
1c280 65 6d 65 6e 74 20 74 68 61 74 20 63 61 6e 0a 2a  ement that can.*
1c290 2a 20 62 65 20 62 6f 75 6e 64 2e 3c 2f 64 64 3e  * be bound.</dd>
1c2a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1c2b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
1c2c0 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
1c2d0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1c2e0 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
1c2f0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
1c300 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
1c310 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
1c320 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
1c330 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1c340 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
1c350 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
1c360 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
1c370 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
1c380 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
1c390 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
1c3a0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
1c3b0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
1c3c0 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
1c3d0 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
1c3e0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
1c3f0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
1c400 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
1c410 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1c420 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
1c430 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
1c440 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1c450 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
1c460 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
1c470 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1c480 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
1c490 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
1c4a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1c4b0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
1c4c0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
1c4d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1c4e0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1c4f0 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
1c500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1c510 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
1c520 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
1c530 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c540 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
1c550 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
1c560 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
1c570 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
1c580 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
1c590 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
1c5a0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
1c5b0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
1c5c0 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
1c5d0 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
1c5e0 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
1c5f0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
1c600 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
1c610 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
1c620 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1c630 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
1c640 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
1c650 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1c660 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1c670 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1c680 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1c690 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
1c6a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c6b0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
1c6c0 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
1c6d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
1c6e0 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
1c6f0 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
1c700 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
1c710 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
1c720 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1c730 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
1c740 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1c750 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1c760 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
1c770 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
1c780 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
1c790 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
1c7a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1c7b0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
1c7c0 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
1c7d0 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
1c7e0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
1c7f0 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
1c800 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
1c810 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
1c820 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
1c830 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1c840 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
1c850 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1c860 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
1c870 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
1c880 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
1c890 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
1c8a0 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
1c8b0 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
1c8c0 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
1c8d0 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
1c8e0 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
1c8f0 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
1c900 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
1c910 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
1c920 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
1c930 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
1c940 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
1c950 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
1c960 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
1c970 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
1c980 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
1c990 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
1c9a0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
1c9b0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
1c9c0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
1c9d0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
1c9e0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1c9f0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
1ca00 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
1ca10 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a  minator bytes..*
1ca20 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
1ca30 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
1ca40 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
1ca50 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
1ca60 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
1ca70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
1ca80 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
1ca90 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
1caa0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1cab0 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
1cac0 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
1cad0 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
1cae0 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
1caf0 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
1cb00 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
1cb10 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
1cb20 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
1cb30 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
1cb40 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
1cb50 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1cb60 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
1cb70 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1cb80 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
1cb90 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
1cba0 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
1cbb0 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
1cbc0 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
1cbd0 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
1cbe0 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
1cbf0 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
1cc00 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
1cc10 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
1cc20 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
1cc30 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
1cc40 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
1cc50 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
1cc60 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
1cc70 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
1cc80 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
1cc90 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
1cca0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
1ccb0 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
1ccc0 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
1ccd0 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
1cce0 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
1ccf0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1cd00 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
1cd10 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
1cd20 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
1cd30 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
1cd40 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1cd50 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1cd60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1cd70 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1cd80 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
1cd90 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
1cda0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
1cdb0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
1cdc0 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
1cdd0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
1cde0 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
1cdf0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1ce00 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
1ce10 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
1ce20 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
1ce30 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
1ce40 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
1ce50 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
1ce60 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
1ce70 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
1ce80 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
1ce90 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
1cea0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
1ceb0 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
1cec0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1ced0 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
1cee0 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
1cef0 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
1cf00 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
1cf10 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
1cf20 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
1cf30 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
1cf40 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
1cf50 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
1cf60 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
1cf70 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
1cf80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1cf90 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
1cfa0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
1cfb0 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
1cfc0 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
1cfd0 6e 20 69 74 20 61 67 61 69 6e 2e 20 20 5e 49 66  n it again.  ^If
1cfe0 20 74 68 65 20 73 63 68 65 6d 61 20 68 61 73 20   the schema has 
1cff0 63 68 61 6e 67 65 64 20 69 6e 0a 2a 2a 20 61 20  changed in.** a 
1d000 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 74  way that makes t
1d010 68 65 20 73 74 61 74 65 6d 65 6e 74 20 6e 6f 20  he statement no 
1d020 6c 6f 6e 67 65 72 20 76 61 6c 69 64 2c 20 5b 73  longer valid, [s
1d030 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1d040 69 6c 6c 20 73 74 69 6c 6c 0a 2a 2a 20 72 65 74  ill still.** ret
1d050 75 72 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  urn [SQLITE_SCHE
1d060 4d 41 5d 2e 20 20 42 75 74 20 75 6e 6c 69 6b 65  MA].  But unlike
1d070 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
1d080 76 69 6f 72 2c 20 5b 53 51 4c 49 54 45 5f 53 43  vior, [SQLITE_SC
1d090 48 45 4d 41 5d 20 69 73 0a 2a 2a 20 6e 6f 77 20  HEMA] is.** now 
1d0a0 61 20 66 61 74 61 6c 20 65 72 72 6f 72 2e 20 20  a fatal error.  
1d0b0 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
1d0c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1d0d0 67 61 69 6e 20 77 69 6c 6c 20 6e 6f 74 20 6d 61  gain will not ma
1d0e0 6b 65 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20  ke the.** error 
1d0f0 67 6f 20 61 77 61 79 2e 20 20 4e 6f 74 65 3a 20  go away.  Note: 
1d100 75 73 65 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  use [sqlite3_err
1d110 6d 73 67 28 29 5d 20 74 6f 20 66 69 6e 64 20 74  msg()] to find t
1d120 68 65 20 74 65 78 74 0a 2a 2a 20 6f 66 20 74 68  he text.** of th
1d130 65 20 70 61 72 73 69 6e 67 20 65 72 72 6f 72 20  e parsing error 
1d140 74 68 61 74 20 72 65 73 75 6c 74 73 20 69 6e 20  that results in 
1d150 61 6e 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  an [SQLITE_SCHEM
1d160 41 5d 20 72 65 74 75 72 6e 2e 0a 2a 2a 20 3c 2f  A] return..** </
1d170 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
1d180 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
1d190 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
1d1a0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
1d1b0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
1d1c0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
1d1d0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
1d1e0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
1d1f0 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
1d200 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
1d210 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
1d220 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
1d230 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
1d240 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
1d250 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
1d260 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
1d270 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
1d280 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
1d290 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
1d2a0 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
1d2b0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
1d2c0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
1d2d0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
1d2e0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
1d2f0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
1d300 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
1d310 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
1d320 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
1d330 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
1d340 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
1d350 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
1d360 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  If the value of 
1d370 61 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  a [parameter | h
1d380 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
1d390 6e 20 74 68 65 20 57 48 45 52 45 20 63 6c 61 75  n the WHERE clau
1d3a0 73 65 20 6d 69 67 68 74 0a 2a 2a 20 63 68 61 6e  se might.** chan
1d3b0 67 65 20 74 68 65 20 71 75 65 72 79 20 70 6c 61  ge the query pla
1d3c0 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
1d3d0 74 2c 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  t, then the stat
1d3e0 65 6d 65 6e 74 20 6d 61 79 20 62 65 0a 2a 2a 20  ement may be.** 
1d3f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
1d400 63 6f 6d 70 69 6c 65 64 20 28 61 73 20 69 66 20  compiled (as if 
1d410 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 61  there had been a
1d420 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 29 20   schema change) 
1d430 6f 6e 20 74 68 65 20 66 69 72 73 74 20 0a 2a 2a  on the first .**
1d440 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d450 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
1d460 20 61 6e 79 20 63 68 61 6e 67 65 20 74 6f 20 74   any change to t
1d470 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
1d480 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
1d490 69 6e 67 73 5d 20 6f 66 20 74 68 65 20 5b 70 61  ings] of the [pa
1d4a0 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 3c 2f  rameter]. .** </
1d4b0 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
1d4c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
1d4d0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
1d4e0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1d4f0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1d500 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1d510 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
1d520 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1d530 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
1d540 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
1d550 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
1d560 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
1d570 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
1d580 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
1d590 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
1d5a0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
1d5b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1d5c0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
1d5d0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
1d5e0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
1d5f0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
1d600 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
1d610 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
1d620 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1d630 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1d640 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1d650 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1d660 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1d670 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
1d680 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1d690 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1d6a0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1d6b0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1d6c0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1d6d0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1d6e0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1d6f0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1d700 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
1d710 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1d720 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1d730 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1d740 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
1d750 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
1d760 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1d770 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1d780 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1d790 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1d7a0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1d7b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1d7c0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1d7d0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1d7e0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1d7f0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1d800 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1d810 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1d820 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1d830 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1d840 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1d850 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
1d860 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1d870 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1d880 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
1d890 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
1d8a0 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
1d8b0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1d8c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
1d8d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
1d8e0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
1d8f0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
1d900 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
1d910 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1d920 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1d930 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1d940 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1d950 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1d960 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1d970 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1d980 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1d990 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
1d9a0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1d9b0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1d9c0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1d9d0 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
1d9e0 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
1d9f0 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
1da00 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
1da10 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1da20 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
1da30 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
1da40 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
1da50 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
1da60 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
1da70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
1da80 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
1da90 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
1daa0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
1dab0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1dac0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
1dad0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
1dae0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
1daf0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
1db00 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
1db10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1db20 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
1db30 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
1db40 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
1db50 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
1db60 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
1db70 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
1db80 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
1db90 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
1dba0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1dbb0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
1dbc0 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
1dbd0 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
1dbe0 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
1dbf0 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
1dc00 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
1dc10 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
1dc20 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
1dc30 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
1dc40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1dc50 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
1dc60 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
1dc70 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
1dc80 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
1dc90 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
1dca0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
1dcb0 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
1dcc0 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
1dcd0 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
1dce0 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
1dcf0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
1dd00 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1dd10 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
1dd20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
1dd30 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
1dd40 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
1dd50 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
1dd60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
1dd70 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
1dd80 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
1dd90 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
1dda0 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
1ddb0 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
1ddc0 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
1ddd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1dde0 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  3_value..**.** T
1ddf0 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63  he terms "protec
1de00 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74  ted" and "unprot
1de10 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20  ected" refer to 
1de20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a  whether or not.*
1de30 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c  * a mutex is hel
1de40 64 2e 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d  d.  A internal m
1de50 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
1de60 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
1de70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1de80 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
1de90 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
1dea0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
1deb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1dec0 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
1ded0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
1dee0 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
1def0 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
1df00 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
1df10 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
1df20 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
1df30 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
1df40 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
1df50 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
1df60 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
1df70 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
1df80 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
1df90 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
1dfa0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
1dfb0 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
1dfc0 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
1dfd0 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
1dfe0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
1dff0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1e000 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
1e010 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
1e020 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
1e030 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
1e040 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
1e050 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
1e060 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
1e070 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
1e080 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
1e090 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
1e0a0 20 62 65 74 77 65 65 6e 20 62 65 74 77 65 65 6e   between between
1e0b0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
1e0c0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
1e0d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
1e0e0 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
1e0f0 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
1e100 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
1e110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1e120 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
1e130 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
1e140 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
1e150 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1e160 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
1e170 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
1e180 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
1e190 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
1e1a0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1e1b0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
1e1c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
1e1d0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
1e1e0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
1e1f0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1e200 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
1e210 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
1e220 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
1e230 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
1e240 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
1e250 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
1e260 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
1e270 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
1e280 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
1e290 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
1e2a0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
1e2b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1e2c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
1e2d0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
1e2e0 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
1e2f0 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
1e300 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
1e310 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
1e320 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
1e330 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
1e340 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
1e350 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
1e360 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
1e370 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
1e380 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
1e390 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
1e3a0 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
1e3b0 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
1e3c0 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
1e3d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1e3e0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
1e3f0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1e400 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1e410 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
1e420 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
1e430 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
1e440 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
1e450 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
1e460 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
1e470 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
1e480 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
1e490 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
1e4a0 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
1e4b0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
1e4c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
1e4d0 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
1e4e0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
1e4f0 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
1e500 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
1e510 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
1e520 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
1e530 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
1e540 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
1e550 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
1e560 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
1e570 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
1e580 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
1e590 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
1e5a0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
1e5b0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
1e5c0 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
1e5d0 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
1e5e0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
1e5f0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
1e600 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e  binding}.**.** ^
1e610 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
1e620 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
1e630 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
1e640 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
1e650 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
1e660 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
1e670 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
1e680 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
1e690 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
1e6a0 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
1e6b0 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
1e6c0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
1e6d0 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
1e6e0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
1e6f0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
1e700 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
1e710 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
1e720 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
1e730 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
1e740 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
1e750 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
1e760 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
1e770 72 69 63 20 69 64 65 6e 74 69 66 65 72 2e 29 5e  ric identifer.)^
1e780 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66    ^The values of
1e790 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65   these.** parame
1e7a0 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65  ters (also calle
1e7b0 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65  d "host paramete
1e7c0 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c  r names" or "SQL
1e7d0 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a   parameters").**
1e7e0 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e   can be set usin
1e7f0 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  g the sqlite3_bi
1e800 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
1e810 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a  defined here..**
1e820 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
1e830 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
1e840 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1e850 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61  routines is alwa
1e860 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ys.** a pointer 
1e870 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1e880 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74  stmt] object ret
1e890 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73  urned from.** [s
1e8a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e8b0 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  2()] or its vari
1e8c0 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ants..**.** ^The
1e8d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
1e8e0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
1e8f0 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74   the SQL paramet
1e900 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a  er to be set..**
1e910 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53   ^The leftmost S
1e920 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  QL parameter has
1e930 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20   an index of 1. 
1e940 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20   ^When the same 
1e950 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72  named.** SQL par
1e960 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d  ameter is used m
1e970 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73  ore than once, s
1e980 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
1e990 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e  uent.** occurren
1e9a0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d  ces have the sam
1e9b0 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66  e index as the f
1e9c0 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e  irst occurrence.
1e9d0 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66  .** ^The index f
1e9e0 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  or named paramet
1e9f0 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65  ers can be looke
1ea00 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a  d up using the.*
1ea10 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
1ea20 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
1ea30 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65  )] API if desire
1ea40 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a  d.  ^The index.*
1ea50 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72  * for "?NNN" par
1ea60 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76  ameters is the v
1ea70 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20  alue of NNN..** 
1ea80 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d  ^The NNN value m
1ea90 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31  ust be between 1
1eaa0 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65   and the [sqlite
1eab0 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61  3_limit()].** pa
1eac0 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f  rameter [SQLITE_
1ead0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
1eae0 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20  UMBER] (default 
1eaf0 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a  value: 999)..**.
1eb00 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  ** ^The third ar
1eb10 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61  gument is the va
1eb20 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74  lue to bind to t
1eb30 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1eb40 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
1eb50 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
1eb60 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
1eb70 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
1eb80 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1eb90 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
1eba0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
1ebb0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
1ebc0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
1ebd0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
1ebe0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
1ebf0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
1ec00 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
1ec10 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
1ec20 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
1ec30 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c   negative, the l
1ec40 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72  ength of the str
1ec50 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75  ing is.** the nu
1ec60 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70  mber of bytes up
1ec70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65   to the first ze
1ec80 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ro terminator..*
1ec90 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20  *.** ^The fifth 
1eca0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1ecb0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
1ecc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
1ecd0 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c  xt(), and.** sql
1ece0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
1ecf0 28 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74  () is a destruct
1ed00 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f  or used to dispo
1ed10 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
1ed20 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65  r.** string afte
1ed30 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e  r SQLite has fin
1ed40 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 5e  ished with it. ^
1ed50 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
1ed60 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
1ed70 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
1ed80 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
1ed90 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
1eda0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
1edb0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
1edc0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
1edd0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
1ede0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
1edf0 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
1ee00 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
1ee10 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
1ee20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
1ee30 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
1ee40 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
1ee50 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
1ee60 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
1ee70 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
1ee80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
1ee90 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
1eea0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
1eeb0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
1eec0 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
1eed0 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
1eee0 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
1eef0 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
1ef00 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
1ef10 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
1ef20 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
1ef30 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
1ef40 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
1ef50 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
1ef60 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
1ef70 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
1ef80 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
1ef90 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
1efa0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
1efb0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
1efc0 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
1efd0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
1efe0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
1eff0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
1f000 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
1f010 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
1f020 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
1f030 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
1f040 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
1f050 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
1f060 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
1f070 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
1f080 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
1f090 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
1f0a0 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
1f0b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
1f0c0 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
1f0d0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
1f0e0 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
1f0f0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
1f100 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
1f110 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
1f120 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
1f130 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
1f140 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
1f150 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
1f160 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
1f170 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
1f180 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
1f190 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
1f1a0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1f1b0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
1f1c0 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
1f1d0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
1f1e0 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
1f1f0 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
1f200 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
1f210 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
1f220 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
1f230 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
1f240 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
1f250 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
1f260 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
1f270 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1f280 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1f290 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
1f2a0 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
1f2b0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
1f2c0 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
1f2d0 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
1f2e0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
1f2f0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
1f300 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
1f310 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
1f320 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
1f330 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1f340 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
1f350 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1f360 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
1f370 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
1f380 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
1f390 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
1f3a0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1f3b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
1f3c0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
1f3d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
1f3e0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
1f3f0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
1f400 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
1f410 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
1f420 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
1f430 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
1f440 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
1f450 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
1f460 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
1f470 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
1f480 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
1f490 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
1f4a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
1f4b0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
1f4c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
1f4d0 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
1f4e0 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
1f4f0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
1f500 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
1f510 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
1f520 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
1f530 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
1f540 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
1f550 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
1f560 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
1f570 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
1f580 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
1f590 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
1f5a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
1f5b0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
1f5c0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
1f5d0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
1f5e0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
1f5f0 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
1f600 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
1f610 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
1f620 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54  ameters.**.** ^T
1f630 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
1f640 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
1f650 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
1f660 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
1f670 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
1f680 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
1f690 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
1f6a0 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
1f6b0 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
1f6c0 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
1f6d0 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
1f6e0 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
1f6f0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
1f700 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
1f710 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1f720 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
1f730 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
1f740 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
1f750 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
1f760 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
1f770 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
1f780 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
1f790 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
1f7a0 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
1f7b0 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
1f7c0 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
1f7d0 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
1f7e0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
1f7f0 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
1f800 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
1f810 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
1f820 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
1f830 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
1f840 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
1f850 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1f860 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
1f870 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
1f880 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1f890 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
1f8a0 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
1f8b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1f8c0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
1f8d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f8e0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
1f8f0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
1f900 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
1f910 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
1f920 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
1f930 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1f940 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
1f950 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
1f960 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
1f970 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1f980 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
1f990 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
1f9a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f9b0 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
1f9c0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
1f9d0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
1f9e0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
1f9f0 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
1fa00 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
1fa10 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
1fa20 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
1fa30 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
1fa40 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
1fa50 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
1fa60 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
1fa70 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
1fa80 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
1fa90 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
1faa0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
1fab0 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
1fac0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
1fad0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
1fae0 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
1faf0 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
1fb00 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
1fb10 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
1fb20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
1fb30 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
1fb40 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
1fb50 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
1fb60 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
1fb70 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1fb80 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
1fb90 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
1fba0 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
1fbb0 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
1fbc0 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
1fbd0 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
1fbe0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
1fbf0 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
1fc00 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
1fc10 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
1fc20 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
1fc30 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
1fc40 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
1fc50 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1fc60 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
1fc70 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1fc80 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
1fc90 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
1fca0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
1fcb0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
1fcc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
1fcd0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
1fce0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1fcf0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1fd00 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
1fd10 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1fd20 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
1fd30 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
1fd40 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
1fd50 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
1fd60 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
1fd70 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
1fd80 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
1fd90 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
1fda0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
1fdb0 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
1fdc0 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
1fdd0 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
1fde0 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
1fdf0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
1fe00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1fe10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
1fe20 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
1fe30 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
1fe40 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
1fe50 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
1fe60 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
1fe70 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
1fe80 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
1fe90 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
1fea0 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
1feb0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
1fec0 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
1fed0 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
1fee0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1fef0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
1ff00 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1ff10 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
1ff20 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
1ff30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
1ff40 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
1ff50 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
1ff60 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
1ff70 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
1ff80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
1ff90 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
1ffa0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
1ffb0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
1ffc0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
1ffd0 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
1ffe0 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
1fff0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
20000 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
20010 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
20020 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
20030 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
20040 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
20050 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
20060 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
20070 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
20080 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
20090 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
200a0 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
200b0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
200c0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
200d0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
200e0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
200f0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
20100 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
20110 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
20120 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
20130 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
20140 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
20150 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
20160 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
20170 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
20180 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
20190 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
201a0 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
201b0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
201c0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
201d0 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
201e0 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
201f0 45 5d 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  E])..*/.int sqli
20200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
20210 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
20220 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
20230 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
20240 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
20250 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73   Set.**.** ^Thes
20260 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
20270 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67  n the name assig
20280 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75  ned to a particu
20290 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e  lar column.** in
202a0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
202b0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  of a [SELECT] st
202c0 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73  atement.  ^The s
202d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
202e0 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  me().** interfac
202f0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
20300 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
20310 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
20320 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c  tring.** and sql
20330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
20340 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  16() returns a p
20350 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
20360 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
20370 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
20380 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
20390 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70  ter is the [prep
203a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
203b0 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ** that implemen
203c0 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  ts the [SELECT] 
203d0 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20  statement. ^The 
203e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
203f0 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   is the.** colum
20400 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20  n number.  ^The 
20410 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
20420 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a  is number 0..**.
20430 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
20440 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
20450 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65  is valid until e
20460 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61  ither the [prepa
20470 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
20480 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62  * is destroyed b
20490 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  y [sqlite3_final
204a0 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
204b0 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
204c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
204d0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
204e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
204f0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
20500 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
20510 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
20520 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
20530 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
20540 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
20550 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
20560 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
20570 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
20580 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
20590 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
205a0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
205b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
205c0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
205d0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
205e0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
205f0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
20600 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
20610 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
20620 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
20630 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
20640 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
20650 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
20660 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
20670 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
20680 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
20690 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
206a0 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  t..*/.const char
206b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
206c0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
206d0 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e  mt*, int N);.con
206e0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
206f0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73  _column_name16(s
20700 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
20710 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t N);../*.** CAP
20720 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66  I3REF: Source Of
20730 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79   Data In A Query
20740 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54   Result.**.** ^T
20750 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
20760 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
20770 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
20780 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
20790 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
207a0 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
207b0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
207c0 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
207d0 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
207e0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
207f0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
20800 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
20810 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
20820 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
20830 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
20840 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
20850 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
20860 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
20870 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
20880 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
20890 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
208a0 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
208b0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
208c0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
208d0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
208e0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
208f0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
20900 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
20910 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
20920 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
20930 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
20940 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
20950 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
20960 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
20970 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
20980 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61  ed.** again in a
20990 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64   different encod
209a0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ing..**.** ^The 
209b0 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61  names returned a
209c0 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  re the original 
209d0 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73  un-aliased names
209e0 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   of the.** datab
209f0 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20  ase, table, and 
20a00 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  column..**.** ^T
20a10 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
20a20 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  t to these inter
20a30 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70  faces is a [prep
20a40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
20a50 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
20a60 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ions return info
20a70 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68  rmation about th
20a80 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c  e Nth result col
20a90 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a  umn returned by.
20aa0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
20ab0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
20ac0 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
20ad0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
20ae0 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c  he left-most col
20af0 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20  umn is column 0 
20b00 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e  for these routin
20b10 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  es..**.** ^If th
20b20 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74  e Nth column ret
20b30 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61  urned by the sta
20b40 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70  tement is an exp
20b50 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75  ression or.** su
20b60 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f  bquery and is no
20b70 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65  t a column value
20b80 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68  , then all of th
20b90 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
20ba0 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e  turn.** NULL.  ^
20bb0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69  These routine mi
20bc0 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20  ght also return 
20bd0 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79  NULL if a memory
20be0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
20bf0 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f  r.** occurs.  ^O
20c00 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72  therwise, they r
20c10 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f  eturn the name o
20c20 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64  f the attached d
20c30 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a  atabase, table,.
20c40 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61  ** or column tha
20c50 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63  t query result c
20c60 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63  olumn was extrac
20c70 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20  ted from..**.** 
20c80 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68  ^As with all oth
20c90 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20  er SQLite APIs, 
20ca0 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65  those whose name
20cb0 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20  s end with "16" 
20cc0 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36  return.** UTF-16
20cd0 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73   encoded strings
20ce0 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66   and the other f
20cf0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
20d00 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  UTF-8..**.** ^Th
20d10 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c  ese APIs are onl
20d20 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74  y available if t
20d30 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63  he library was c
20d40 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
20d50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
20d60 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41  LE_COLUMN_METADA
20d70 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73  TA] C-preprocess
20d80 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a  or symbol..**.**
20d90 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
20da0 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65  threads call one
20db0 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73   or more of thes
20dc0 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e  e routines again
20dd0 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70  st the same.** p
20de0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20df0 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20  t and column at 
20e00 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
20e10 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
20e20 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  re.** undefined.
20e30 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72  .**.** If two or
20e40 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61   more threads ca
20e50 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  ll one or more.*
20e60 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
20e70 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20  n_database_name 
20e80 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74  | column metadat
20e90 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a  a interfaces].**
20ea0 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70   for the same [p
20eb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
20ec0 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f  t] and result co
20ed0 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73  lumn.** at the s
20ee0 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
20ef0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
20f00 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73  defined..*/.cons
20f10 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
20f20 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
20f30 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
20f40 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
20f50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
20f60 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
20f70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
20f80 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68  *,int);.const ch
20f90 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
20fa0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
20fb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
20fc0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
20fd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
20fe0 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
20ff0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
21000 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
21010 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
21020 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
21030 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76  t*,int);.const v
21040 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
21050 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
21060 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
21070 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
21080 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
21090 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
210a0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
210b0 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72   ^(The first par
210c0 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65  ameter is a [pre
210d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
210e0 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61  ..** If this sta
210f0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c  tement is a [SEL
21100 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ECT] statement a
21110 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  nd the Nth colum
21120 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75  n of the.** retu
21130 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20  rned result set 
21140 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d  of that [SELECT]
21150 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75   is a table colu
21160 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78  mn (not an.** ex
21170 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
21180 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64  uery) then the d
21190 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20  eclared type of 
211a0 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c  the table.** col
211b0 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  umn is returned.
211c0 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20  )^  ^If the Nth 
211d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
211e0 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a  sult set is an.*
211f0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
21200 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61  subquery, then a
21210 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
21220 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54   returned..** ^T
21230 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
21240 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46  ng is always UTF
21250 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a  -8 encoded..**.*
21260 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
21270 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62   given the datab
21280 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a  ase schema:.**.*
21290 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74  * CREATE TABLE t
212a0 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a  1(c1 VARIANT);.*
212b0 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c  *.** and the fol
212c0 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  lowing statement
212d0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a   to be compiled:
212e0 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31  .**.** SELECT c1
212f0 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31   + 1, c1 FROM t1
21300 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ;.**.** this rou
21310 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72  tine would retur
21320 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41  n the string "VA
21330 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73  RIANT" for the s
21340 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20  econd result.** 
21350 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61  column (i==1), a
21360 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nd a NULL pointe
21370 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  r for the first 
21380 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69  result column (i
21390 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53  ==0).)^.**.** ^S
213a0 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d  QLite uses dynam
213b0 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69  ic run-time typi
213c0 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65  ng.  ^So just be
213d0 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a  cause a column.*
213e0 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f  * is declared to
213f0 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69   contain a parti
21400 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20  cular type does 
21410 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68  not mean that th
21420 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64  e.** data stored
21430 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20   in that column 
21440 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72  is of the declar
21450 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65  ed type.  SQLite
21460 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20   is.** strongly 
21470 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74  typed, but the t
21480 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63  yping is dynamic
21490 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54   not static.  ^T
214a0 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69  ype.** is associ
214b0 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69  ated with indivi
214c0 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74  dual values, not
214d0 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69   with the contai
214e0 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20  ners.** used to 
214f0 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65  hold those value
21500 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  s..*/.const char
21510 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
21520 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
21530 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
21540 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
21550 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
21560 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
21570 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  *,int);../*.** C
21580 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74  API3REF: Evaluat
21590 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  e An SQL Stateme
215a0 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61  nt.**.** After a
215b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
215c0 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70  ment] has been p
215d0 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69  repared using ei
215e0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
215f0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
21600 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
21610 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  re16_v2()] or on
21620 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a  e of the legacy.
21630 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73  ** interfaces [s
21640 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
21650 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
21660 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73  epare16()], this
21670 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73   function.** mus
21680 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20  t be called one 
21690 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f  or more times to
216a0 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74   evaluate the st
216b0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  atement..**.** T
216c0 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68  he details of th
216d0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68  e behavior of th
216e0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
216f0 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e   interface depen
21700 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  d.** on whether 
21710 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61  the statement wa
21720 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  s prepared using
21730 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20   the newer "v2" 
21740 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71  interface.** [sq
21750 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21760 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
21770 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
21780 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65   or the older le
21790 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
217a0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
217b0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
217c0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e  e3_prepare16()].
217d0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
217e0 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74  .** new "v2" int
217f0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
21800 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70  ended for new ap
21810 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74  plications but t
21820 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
21830 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74  erface will cont
21840 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f  inue to be suppo
21850 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  rted..**.** ^In 
21860 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
21870 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e  face, the return
21880 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65   value will be e
21890 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55  ither [SQLITE_BU
218a0 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  SY],.** [SQLITE_
218b0 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52  DONE], [SQLITE_R
218c0 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  OW], [SQLITE_ERR
218d0 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OR], or [SQLITE_
218e0 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74  MISUSE]..** ^Wit
218f0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
21900 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65  face, any of the
21910 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63   other [result c
21920 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  odes] or.** [ext
21930 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
21940 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  es] might be ret
21950 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a  urned as well..*
21960 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55  *.** ^[SQLITE_BU
21970 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SY] means that t
21980 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69  he database engi
21990 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f  ne was unable to
219a0 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20   acquire the.** 
219b0 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69  database locks i
219c0 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74  t needs to do it
219d0 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20  s job.  ^If the 
219e0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
219f0 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63  COMMIT].** or oc
21a00 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20  curs outside of 
21a10 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
21a20 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f  saction, then yo
21a30 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a  u can retry the.
21a40 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49  ** statement.  I
21a50 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
21a60 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54  is not a [COMMIT
21a70 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74  ] and occurs wit
21a80 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69  hin a.** explici
21a90 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
21aa0 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
21ab0 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
21ac0 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
21ad0 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
21ae0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
21af0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
21b00 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
21b10 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
21b20 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
21b30 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
21b40 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
21b50 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
21b60 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
21b70 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
21b80 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
21b90 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
21ba0 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
21bb0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
21bc0 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
21bd0 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
21be0 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
21bf0 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
21c00 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
21c10 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
21c20 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
21c30 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
21c40 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
21c50 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
21c60 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
21c70 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
21c80 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
21c90 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
21ca0 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
21cb0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
21cc0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
21cd0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
21ce0 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
21cf0 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
21d00 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
21d10 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
21d20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
21d30 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
21d40 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
21d50 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
21d60 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
21d70 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
21d80 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
21d90 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
21da0 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
21db0 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
21dc0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
21dd0 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
21de0 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
21df0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
21e00 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
21e10 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
21e20 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
21e30 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
21e40 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
21e50 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
21e60 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
21e70 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
21e80 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
21e90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
21ea0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
21eb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
21ec0 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
21ed0 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
21ee0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
21ef0 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
21f00 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
21f10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
21f20 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
21f30 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
21f40 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
21f50 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
21f60 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
21f70 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
21f80 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
21f90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
21fa0 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
21fb0 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
21fc0 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
21fd0 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
21fe0 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
21ff0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
22000 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
22010 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
22020 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
22030 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
22040 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
22050 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22060 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
22070 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
22080 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
22090 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
220a0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
220b0 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
220c0 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
220d0 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
220e0 2e 31 2c 20 69 74 20 77 61 73 20 72 65 71 75 69  .1, it was requi
220f0 72 65 64 0a 2a 2a 20 61 66 74 65 72 20 73 71 6c  red.** after sql
22100 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75  ite3_step() retu
22110 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 20 6f 74  rned anything ot
22120 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
22130 5f 52 4f 57 5d 20 74 68 61 74 0a 2a 2a 20 5b 73  _ROW] that.** [s
22140 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
22150 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65  be called before
22160 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
22170 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
22180 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
22190 20 20 46 61 69 6c 75 72 65 20 74 6f 20 69 6e 76    Failure to inv
221a0 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  oke [sqlite3_res
221b0 65 74 28 29 5d 20 69 6e 20 74 68 69 73 20 77 61  et()] in this wa
221c0 79 20 77 6f 75 6c 64 0a 2a 2a 20 72 65 73 75 6c  y would.** resul
221d0 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  t in an [SQLITE_
221e0 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66  MISUSE] return f
221f0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 74 65 70  rom sqlite3_step
22200 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 0a 2a  ().  But after.*
22210 2a 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33  * version 3.6.23
22220 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .1, sqlite3_step
22230 28 29 20 62 65 67 61 6e 20 63 61 6c 6c 69 6e 67  () began calling
22240 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
22250 29 5d 20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63  )] .** automatic
22260 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
22270 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
22280 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
22290 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
222a0 20 20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66    .**.** <b>Goof
222b0 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
222c0 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
222d0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
222e0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
222f0 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
22300 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
22310 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
22320 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
22330 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
22340 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
22350 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
22360 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
22370 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
22380 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
22390 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
223a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
223b0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
223c0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
223d0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
223e0 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
223f0 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
22400 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
22410 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
22420 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
22430 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
22440 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
22450 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
22460 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
22470 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
22480 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
22490 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
224a0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
224b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
224c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
224d0 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
224e0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
224f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
22500 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
22510 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
22520 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
22530 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
22540 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
22550 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
22560 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
22570 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
22580 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
22590 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
225a0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69  ecommended..*/.i
225b0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
225c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
225d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
225e0 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
225f0 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
22600 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  et.**.** ^The sq
22610 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
22620 28 50 29 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  (P) the number o
22630 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
22640 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
22650 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
22660 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
22670 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
22680 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
22690 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
226a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
226b0 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
226c0 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
226d0 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
226e0 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
226f0 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
22700 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
22710 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
22720 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
22730 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
22740 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
22750 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
22760 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
22770 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
22780 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
22790 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
227a0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
227b0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
227c0 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
227d0 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
227e0 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
227f0 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
22800 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
22810 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
22820 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
22830 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
22840 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
22850 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
22860 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
22870 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
22880 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
22890 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
228a0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
228b0 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
228c0 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
228d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
228e0 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
228f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
22900 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
22910 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
22920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22930 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
22940 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
22950 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
22960 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
22970 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
22980 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
22990 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
229a0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
229b0 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
229c0 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
229d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
229e0 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
229f0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  ctions}.**.** Th
22a00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ese routines for
22a10 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65  m the "result se
22a20 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  t" interface..**
22a30 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
22a40 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
22a50 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
22a60 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
22a70 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
22a80 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
22a90 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
22aa0 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
22ab0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
22ac0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
22ad0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22ae0 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
22af0 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
22b00 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
22b10 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
22b20 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
22b30 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
22b40 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
22b50 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
22b60 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
22b70 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
22b80 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
22b90 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
22ba0 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
22bb0 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
22bc0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
22bd0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
22be0 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
22bf0 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
22c00 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
22c10 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
22c20 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
22c30 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
22c40 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
22c50 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
22c60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
22c70 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
22c80 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
22c90 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
22ca0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
22cb0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
22cc0 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
22cd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
22ce0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
22cf0 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
22d00 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
22d10 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
22d20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22d30 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
22d40 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
22d50 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
22d60 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
22d70 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
22d80 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
22d90 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
22da0 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
22db0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
22dc0 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
22dd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
22de0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
22df0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
22e00 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
22e10 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
22e20 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
22e30 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
22e40 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
22e50 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
22e60 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
22e70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
22e80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22e90 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
22ea0 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
22eb0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
22ec0 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
22ed0 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
22ee0 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
22ef0 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
22f00 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
22f10 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
22f20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
22f30 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
22f40 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
22f50 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
22f60 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
22f70 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
22f80 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
22f90 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
22fa0 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
22fb0 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
22fc0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
22fd0 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
22fe0 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
22ff0 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
23000 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
23010 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
23020 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
23030 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
23040 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
23050 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
23060 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
23070 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
23080 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
23090 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
230a0 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
230b0 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
230c0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
230d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
230e0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
230f0 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
23100 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
23110 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
23120 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
23130 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
23140 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
23150 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
23160 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
23170 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
23180 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
23190 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
231a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
231b0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
231c0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
231d0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
231e0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
231f0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
23200 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
23210 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
23220 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
23230 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
23240 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
23250 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
23260 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
23270 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
23280 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
23290 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
232a0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
232b0 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
232c0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
232d0 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
232e0 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
232f0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
23300 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
23310 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
23320 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
23330 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65  ** ^The value re
23340 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20  turned does not 
23350 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
23360 20 74 65 72 6d 69 6e 61 74 6f 72 20 61 74 20 74   terminator at t
23370 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
23380 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
23390 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
233a0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 74 68  e returned is th
233b0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
233c0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
233d0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
233e0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
233f0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
23400 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
23410 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
23420 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
23430 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
23440 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
23450 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
23460 73 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 65  s zero terminate
23470 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
23480 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
23490 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
234a0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
234b0 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 6e  ength BLOB is an
234c0 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 70 6f   arbitrary.** po
234d0 69 6e 74 65 72 2c 20 70 6f 73 73 69 62 6c 79 20  inter, possibly 
234e0 65 76 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  even a NULL poin
234f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
23500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
23510 79 74 65 73 31 36 28 29 20 72 6f 75 74 69 6e 65  ytes16() routine
23520 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 73   is similar to s
23530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
23540 74 65 73 28 29 0a 2a 2a 20 62 75 74 20 6c 65 61  tes().** but lea
23550 76 65 73 20 74 68 65 20 72 65 73 75 6c 74 20 69  ves the result i
23560 6e 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  n UTF-16 in nati
23570 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 6e  ve byte order in
23580 73 74 65 61 64 20 6f 66 20 55 54 46 2d 38 2e 0a  stead of UTF-8..
23590 2a 2a 20 5e 54 68 65 20 7a 65 72 6f 20 74 65 72  ** ^The zero ter
235a0 6d 69 6e 61 74 6f 72 20 69 73 20 6e 6f 74 20 69  minator is not i
235b0 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 69 73 20  ncluded in this 
235c0 63 6f 75 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  count..**.** ^Th
235d0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
235e0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
235f0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
23600 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
23610 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
23620 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75  e] object.  An u
23630 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
23640 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a  e3_value object.
23650 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ** may only be u
23660 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  sed with [sqlite
23670 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
23680 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
23690 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
236a0 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
236b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
236c0 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
236d0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
236e0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
236f0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
23700 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
23710 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
23720 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
23730 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
23740 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
23750 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
23760 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
23770 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
23780 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
23790 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
237a0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
237b0 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
237c0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
237d0 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
237e0 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61  te.  ^For.** exa
237f0 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
23800 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
23810 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
23820 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
23830 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
23840 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
23850 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
23860 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
23870 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
23880 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
23890 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
238a0 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
238b0 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
238c0 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
238d0 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
238e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
238f0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
23900 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
23910 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
23920 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
23930 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
23940 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
23950 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
23960 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
23970 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
23980 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
23990 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
239a0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
239b0 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
239c0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
239d0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
239e0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
239f0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
23a00 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
23a10 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
23a20 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
23a30 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
23a40 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
23a50 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
23a60 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
23a70 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
23a80 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
23a90 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
23aa0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
23ab0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
23ac0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
23ad0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
23ae0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
23af0 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
23b00 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
23b10 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
23b20 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
23b30 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
23b40 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
23b50 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
23b60 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
23b70 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
23b80 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
23b90 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
23ba0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
23bb0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
23bc0 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
23bd0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
23be0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
23bf0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
23c00 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
23c10 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
23c20 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
23c30 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
23c40 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
23c50 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
23c60 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
23c70 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
23c80 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
23c90 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
23ca0 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
23cb0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
23cc0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
23cd0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
23ce0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
23cf0 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
23d00 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
23d10 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
23d20 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
23d30 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
23d40 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
23d50 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
23d60 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  )^.**.** The tab
23d70 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
23d80 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
23d90 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
23da0 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
23db0 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
23dc0 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
23dd0 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
23de0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
23df0 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
23e00 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
23e10 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
23e20 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
23e30 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
23e40 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
23e50 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
23e60 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
23e70 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
23e80 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
23e90 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f  mmers..**.** ^No
23ea0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
23eb0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
23ec0 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
23ed0 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
23ee0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
23ef0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
23f00 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
23f10 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
23f20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
23f30 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
23f40 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
23f50 2a 2a 20 5e 28 54 79 70 65 20 63 6f 6e 76 65 72  ** ^(Type conver
23f60 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
23f70 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
23f80 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
23f90 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
23fa0 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
23fb0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
23fc0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
23fd0 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
23fe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
23ff0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
24000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
24010 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
24020 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
24030 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
24040 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
24050 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
24060 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
24070 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
24080 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
24090 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
240a0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
240b0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
240c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
240d0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
240e0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
240f0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
24100 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
24110 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
24120 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
24130 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
24140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24150 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
24160 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
24170 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
24180 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
24190 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
241a0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
241b0 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
241c0 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  l>)^.**.** ^Conv
241d0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
241e0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
241f0 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
24200 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
24210 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
24220 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
24230 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
24240 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
24250 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
24260 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
24270 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 70 6f  prior pointer po
24280 69 6e 74 73 20 74 6f 20 77 69 6c 6c 20 68 61 76  ints to will hav
24290 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
242a0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
242b0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
242c0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
242d0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
242e0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
242f0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
24300 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
24310 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
24320 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
24330 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
24340 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 61 66 65  **.** ^(The safe
24350 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
24360 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
24370 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
24380 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
24390 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
243a0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
243b0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
243c0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
243d0 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
243e0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
243f0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
24400 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
24410 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
24420 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
24430 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
24440 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
24450 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
24460 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
24470 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
24480 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
24490 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
244a0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
244b0 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
244c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
244d0 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
244e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
244f0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
24500 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
24510 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
24520 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
24530 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
24540 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
24550 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24560 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
24570 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
24580 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
24590 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
245a0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
245b0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
245c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
245d0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
245e0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
245f0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
24600 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24610 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
24620 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
24630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
24640 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
24650 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
24660 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
24670 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
24680 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
24690 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
246a0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
246b0 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
246c0 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
246d0 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
246e0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
246f0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
24700 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
24710 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
24720 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
24730 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
24740 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
24750 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
24760 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
24770 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
24780 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
24790 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
247a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
247b0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
247c0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
247d0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
247e0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
247f0 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
24800 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
24810 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
24820 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
24830 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
24840 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
24850 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
24860 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
24870 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
24880 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
24890 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
248a0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
248b0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
248c0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
248d0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
248e0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
248f0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
24900 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
24910 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
24920 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
24930 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
24940 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
24950 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
24960 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
24970 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
24980 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
24990 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
249a0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
249b0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
249c0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
249d0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
249e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
249f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
24a00 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
24a10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
24a20 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
24a30 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
24a40 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
24a50 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
24a60 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
24a70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
24a80 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
24a90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
24aa0 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
24ab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
24ac0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
24ad0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24ae0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
24af0 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
24b00 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
24b10 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
24b20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
24b30 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
24b40 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
24b50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24b60 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
24b70 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
24b80 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ject.**.** ^The 
24b90 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
24ba0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
24bb0 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
24bc0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
24bd0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
24be0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
24bf0 20 65 78 65 63 75 74 65 64 20 73 75 63 63 65 73   executed succes
24c00 73 66 75 6c 6c 79 20 6f 72 20 6e 6f 74 20 65 78  sfully or not ex
24c10 65 63 75 74 65 64 20 61 74 20 61 6c 6c 2c 20 74  ecuted at all, t
24c20 68 65 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  hen.** SQLITE_OK
24c30 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 5e 49   is returned. ^I
24c40 66 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  f execution of t
24c50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 61 69  he statement fai
24c60 6c 65 64 20 74 68 65 6e 20 61 6e 0a 2a 2a 20 5b  led then an.** [
24c70 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 5b  error code] or [
24c80 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
24c90 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
24ca0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  ..**.** ^This ro
24cb0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
24cc0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
24cd0 20 64 75 72 69 6e 67 20 74 68 65 20 65 78 65 63   during the exec
24ce0 75 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  ution of the.** 
24cf0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24d00 65 6e 74 5d 2e 20 20 5e 49 66 20 74 68 65 20 76  ent].  ^If the v
24d10 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 68  irtual machine h
24d20 61 73 20 6e 6f 74 0a 2a 2a 20 63 6f 6d 70 6c 65  as not.** comple
24d30 74 65 64 20 65 78 65 63 75 74 69 6f 6e 20 77 68  ted execution wh
24d40 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
24d50 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 61 74 20  is called, that 
24d60 69 73 20 6c 69 6b 65 0a 2a 2a 20 65 6e 63 6f 75  is like.** encou
24d70 6e 74 65 72 69 6e 67 20 61 6e 20 65 72 72 6f 72  ntering an error
24d80 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   or an [sqlite3_
24d90 69 6e 74 65 72 72 75 70 74 20 7c 20 69 6e 74 65  interrupt | inte
24da0 72 72 75 70 74 5d 2e 0a 2a 2a 20 5e 49 6e 63 6f  rrupt]..** ^Inco
24db0 6d 70 6c 65 74 65 20 75 70 64 61 74 65 73 20 6d  mplete updates m
24dc0 61 79 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ay be rolled bac
24dd0 6b 20 61 6e 64 20 74 72 61 6e 73 61 63 74 69 6f  k and transactio
24de0 6e 73 20 63 61 6e 63 65 6c 65 64 2c 0a 2a 2a 20  ns canceled,.** 
24df0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
24e00 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
24e10 61 6e 64 20 74 68 65 0a 2a 2a 20 5b 65 72 72 6f  and the.** [erro
24e20 72 20 63 6f 64 65 5d 20 72 65 74 75 72 6e 65 64  r code] returned
24e30 20 77 69 6c 6c 20 62 65 20 5b 53 51 4c 49 54 45   will be [SQLITE
24e40 5f 41 42 4f 52 54 5d 2e 0a 2a 2f 0a 69 6e 74 20  _ABORT]..*/.int 
24e50 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
24e60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
24e70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
24e80 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
24e90 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
24ea0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
24eb0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
24ec0 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
24ed0 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
24ee0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
24ef0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
24f00 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
24f10 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
24f20 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
24f30 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
24f40 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
24f50 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
24f60 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
24f70 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
24f80 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
24f90 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
24fa0 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
24fb0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
24fc0 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
24fd0 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
24fe0 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
24ff0 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
25000 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
25010 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
25020 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
25030 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25040 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
25050 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
25060 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
25070 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
25080 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
25090 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
250a0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
250b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
250c0 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
250d0 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
250e0 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
250f0 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
25100 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
25110 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
25120 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
25130 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
25140 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
25150 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
25160 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
25170 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
25180 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
25190 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
251a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
251b0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
251c0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
251d0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
251e0 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
251f0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
25200 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
25210 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
25220 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
25230 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
25240 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
25250 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
25260 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
25270 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
25280 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e  tement] S..*/.in
25290 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  t sqlite3_reset(
252a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
252b0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
252c0 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72  I3REF: Create Or
252d0 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75   Redefine SQL Fu
252e0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  nctions.** KEYWO
252f0 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63  RDS: {function c
25300 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
25310 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
25320 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
25330 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
25340 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
25350 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
25360 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
25370 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  s}.**.** ^These 
25380 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  two functions (c
25390 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
253a0 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
253b0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
253c0 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
253d0 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
253e0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
253f0 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
25400 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
25410 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
25420 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
25430 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
25440 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 62  nly difference b
25450 65 74 77 65 65 6e 20 74 68 65 0a 2a 2a 20 74 77  etween the.** tw
25460 6f 20 69 73 20 74 68 61 74 20 74 68 65 20 73 65  o is that the se
25470 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2c 20  cond parameter, 
25480 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
25490 28 73 63 61 6c 61 72 29 20 66 75 6e 63 74 69 6f  (scalar) functio
254a0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
254b0 65 2c 20 69 73 20 65 6e 63 6f 64 65 64 20 69 6e  e, is encoded in
254c0 20 55 54 46 2d 38 20 66 6f 72 20 73 71 6c 69 74   UTF-8 for sqlit
254d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
254e0 6f 6e 28 29 20 61 6e 64 20 55 54 46 2d 31 36 0a  on() and UTF-16.
254f0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
25500 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
25510 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ()..**.** ^The f
25520 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
25530 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
25540 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
25550 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
25560 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
25570 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
25580 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
25590 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
255a0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
255b0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
255c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
255d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
255e0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
255f0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
25600 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
25610 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ately..**.** The
25620 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
25630 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
25640 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
25650 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
25660 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
25670 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
25680 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
25690 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
256a0 73 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 0a  s, exclusive of.
256b0 2a 2a 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  ** the zero-term
256c0 69 6e 61 74 6f 72 2e 20 20 4e 6f 74 65 20 74 68  inator.  Note th
256d0 61 74 20 74 68 65 20 6e 61 6d 65 20 6c 65 6e 67  at the name leng
256e0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 62  th limit is in b
256f0 79 74 65 73 2c 20 6e 6f 74 0a 2a 2a 20 63 68 61  ytes, not.** cha
25700 72 61 63 74 65 72 73 2e 20 20 5e 41 6e 79 20 61  racters.  ^Any a
25710 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
25720 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
25730 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
25740 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
25750 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
25760 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
25770 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
25780 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
25790 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
257a0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
257b0 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
257c0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
257d0 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
257e0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
257f0 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
25800 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
25810 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
25820 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
25830 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
25840 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
25850 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
25860 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
25870 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
25880 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
25890 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
258a0 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
258b0 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
258c0 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
258d0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
258e0 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
258f0 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 75 72 74 68  **.** The fourth
25900 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
25910 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
25920 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
25930 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
25940 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
25950 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
25960 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
25970 65 74 65 72 73 2e 20 20 41 6e 79 20 53 51 4c 20  eters.  Any SQL 
25980 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
25990 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  ntation should b
259a0 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a  e able to work.*
259b0 2a 20 77 6f 72 6b 20 77 69 74 68 20 55 54 46 2d  * work with UTF-
259c0 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20  8, UTF-16le, or 
259d0 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73  UTF-16be.  But s
259e0 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ome implementati
259f0 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f  ons may be.** mo
25a00 72 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74  re efficient wit
25a10 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74  h one encoding t
25a20 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41  han another.  ^A
25a30 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
25a40 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  y.** invoke sqli
25a50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
25a60 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ion() or sqlite3
25a70 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
25a80 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  16() multiple.**
25a90 20 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20   times with the 
25aa0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75  same function bu
25ab0 74 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  t with different
25ac0 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74   values of eText
25ad0 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  Rep..** ^When mu
25ae0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
25af0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
25b00 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
25b10 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
25b20 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
25b30 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
25b40 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
25b50 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
25b60 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20  nversion..** If 
25b70 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20  there is only a 
25b80 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  single implement
25b90 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73  ation which does
25ba0 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74   not care what t
25bb0 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20  ext.** encoding 
25bc0 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  is used, then th
25bd0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
25be0 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c  t should be [SQL
25bf0 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20  ITE_ANY]..**.** 
25c00 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61  ^(The fifth para
25c10 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69  meter is an arbi
25c20 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20  trary pointer.  
25c30 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
25c40 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e  on of the.** fun
25c50 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61  ction can gain a
25c60 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f  ccess to this po
25c70 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c  inter using [sql
25c80 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
25c90 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ].)^.**.** The s
25ca0 65 76 65 6e 74 68 2c 20 65 69 67 68 74 68 20 61  eventh, eighth a
25cb0 6e 64 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  nd ninth paramet
25cc0 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
25cd0 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
25ce0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
25cf0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
25d00 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
25d10 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
25d20 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
25d30 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
25d40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
25d50 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
25d60 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
25d70 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
25d80 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
25d90 6e 74 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20  nters should be 
25da0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
25db0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
25dc0 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
25dd0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
25de0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
25df0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
25e00 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
25e10 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
25e20 55 4c 4c 20 73 68 6f 75 6c 64 20 62 65 20 70 61  ULL should be pa
25e30 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20  ssed for xFunc. 
25e40 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78  ^To delete an ex
25e50 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75  isting.** SQL fu
25e60 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
25e70 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 66  ate, pass NULL f
25e80 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
25e90 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 73 2e  ction callbacks.
25ea0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
25eb0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
25ec0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
25ed0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
25ee0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
25ef0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
25f00 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
25f10 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
25f20 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
25f30 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
25f40 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
25f50 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
25f60 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
25f70 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
25f80 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
25f90 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
25fa0 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
25fb0 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
25fc0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
25fd0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
25fe0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
25ff0 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
26000 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
26010 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
26020 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
26030 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
26040 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
26050 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
26060 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
26070 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
26080 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
26090 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
260a0 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
260b0 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
260c0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
260d0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
260e0 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
260f0 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
26100 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
26110 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
26120 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
26130 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
26140 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
26150 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
26160 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
26170 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
26180 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
26190 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
261a0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
261b0 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
261c0 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
261d0 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
261e0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
261f0 6f 6e 73 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ons..** ^The fir
26200 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  st application-d
26210 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
26220 77 69 74 68 20 61 20 67 69 76 65 6e 20 6e 61 6d  with a given nam
26230 65 20 6f 76 65 72 72 69 64 65 73 20 61 6c 6c 0a  e overrides all.
26240 2a 2a 20 62 75 69 6c 74 2d 69 6e 20 66 75 6e 63  ** built-in func
26250 74 69 6f 6e 73 20 69 6e 20 74 68 65 20 73 61 6d  tions in the sam
26260 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
26270 65 63 74 69 6f 6e 5d 20 77 69 74 68 20 74 68 65  ection] with the
26280 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 20 5e   same name..** ^
26290 53 75 62 73 65 71 75 65 6e 74 20 61 70 70 6c 69  Subsequent appli
262a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
262b0 75 6e 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  unctions of the 
262c0 73 61 6d 65 20 6e 61 6d 65 20 6f 6e 6c 79 20 6f  same name only o
262d0 76 65 72 72 69 64 65 20 0a 2a 2a 20 70 72 69 6f  verride .** prio
262e0 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  r application-de
262f0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 20  fined functions 
26300 74 68 61 74 20 61 72 65 20 61 6e 20 65 78 61 63  that are an exac
26310 74 20 6d 61 74 63 68 20 66 6f 72 20 74 68 65 0a  t match for the.
26320 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  ** number of par
26330 61 6d 65 74 65 72 73 20 61 6e 64 20 70 72 65 66  ameters and pref
26340 65 72 72 65 64 20 65 6e 63 6f 64 69 6e 67 2e 0a  erred encoding..
26350 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
26360 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
26370 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
26380 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
26390 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
263a0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
263b0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
263c0 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
263d0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
263e0 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
263f0 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
26400 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
26410 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
26420 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
26430 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
26440 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
26450 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
26460 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
26470 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
26480 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
26490 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
264a0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
264b0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
264c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
264d0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
264e0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
264f0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
26500 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
26510 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
26520 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
26530 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
26540 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
26550 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
26560 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
26570 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
26580 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
26590 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
265a0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
265b0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
265c0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
265d0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
265e0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
265f0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
26600 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
26610 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
26620 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
26630 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
26640 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 0a 2f 2a 0a  ontext*).);../*.
26650 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78  ** CAPI3REF: Tex
26660 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a  t Encodings.**.*
26670 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
26680 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20   define integer 
26690 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65  codes that repre
266a0 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73  sent the various
266b0 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  .** text encodin
266c0 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20  gs supported by 
266d0 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69  SQLite..*/.#defi
266e0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20  ne SQLITE_UTF8  
266f0 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
26700 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
26710 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  E        2.#defi
26720 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
26730 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  E        3.#defi
26740 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
26750 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
26760 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
26770 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
26780 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
26790 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
267a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
267b0 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  unction only */.
267c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
267d0 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20  TF16_ALIGNED  8 
267e0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
267f0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f  eate_collation o
26800 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  nly */../*.** CA
26810 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
26820 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
26830 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
26840 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
26850 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
26860 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
26870 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
26880 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
26890 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
268a0 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
268b0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
268c0 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
268d0 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
268e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
268f0 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
26900 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
26910 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65  unctions.  To he
26920 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f  lp encourage peo
26930 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ple to avoid.** 
26940 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63  using these func
26950 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f  tions, we are no
26960 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20  t going to tell 
26970 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f  you what they do
26980 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
26990 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
269a0 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  TED.SQLITE_DEPRE
269b0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
269c0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
269d0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
269e0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
269f0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
26a00 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
26a10 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
26a20 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
26a30 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
26a40 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
26a50 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
26a60 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
26a70 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
26a80 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
26a90 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
26aa0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
26ab0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
26ac0 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
26ad0 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
26ae0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
26af0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
26b00 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
26b10 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
26b20 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
26b30 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
26b40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
26b50 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
26b60 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
26b70 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  lues.**.** The C
26b80 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
26b90 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
26ba0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
26bb0 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
26bc0 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
26bd0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
26be0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
26bf0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
26c00 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
26c10 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
26c20 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
26c30 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
26c40 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
26c50 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
26c60 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
26c70 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
26c80 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
26c90 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
26ca0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
26cb0 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
26cc0 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
26cd0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
26ce0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
26cf0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68 20  tes..** The 4th 
26d00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
26d10 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
26d20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
26d30 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
26d40 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
26d50 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
26d60 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
26d70 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26d80 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
26d90 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
26da0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
26db0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
26dc0 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
26dd0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
26de0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
26df0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
26e00 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
26e10 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
26e20 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
26e30 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
26e40 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
26e50 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
26e60 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
26e70 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
26e80 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
26e90 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
26ea0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
26eb0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
26ec0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
26ed0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
26ee0 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
26ef0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
26f00 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
26f10 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
26f20 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
26f30 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
26f40 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
26f50 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
26f60 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
26f70 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
26f80 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
26f90 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
26fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
26fb0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
26fc0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
26fd0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
26fe0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
26ff0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
27000 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
27010 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
27020 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
27030 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
27040 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27050 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
27060 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
27070 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
27080 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
27090 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
270a0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
270b0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
270c0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
270d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
270e0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
270f0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
27100 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
27110 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
27120 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
27130 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
27140 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
27150 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
27160 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
27170 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
27180 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
27190 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
271a0 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
271b0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
271c0 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
271d0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
271e0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
271f0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
27200 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
27210 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
27220 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
27230 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
27240 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
27250 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
27260 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
27270 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
27280 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
27290 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
272a0 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
272b0 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
272c0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
272d0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
272e0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
272f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
27300 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
27310 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
27320 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
27330 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
27340 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
27350 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
27360 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
27370 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
27380 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
27390 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
273a0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
273b0 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
273c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
273d0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
273e0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
273f0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
27400 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
27410 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
27420 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
27430 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f  arameters..*/.co
27440 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
27450 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
27460 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
27470 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
27480 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
27490 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
274a0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
274b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
274c0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
274d0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
274e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
274f0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
27500 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
27510 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
27520 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
27530 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
27540 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
27550 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
27560 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
27570 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
27580 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
27590 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
275a0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
275b0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
275c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
275d0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
275e0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
275f0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
27600 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
27610 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
27620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
27630 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
27640 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
27650 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
27660 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
27670 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
27680 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
27690 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
276a0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
276b0 6c 65 6d 65 6e 74 69 6f 6e 73 20 6f 66 20 61 67  lementions of ag
276c0 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
276d0 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a  tions use this.*
276e0 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c  * routine to all
276f0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72  ocate memory for
27700 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73   storing their s
27710 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tate..**.** ^The
27720 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20   first time the 
27730 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
27740 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
27750 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
27760 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69   .** for a parti
27770 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20  cular aggregate 
27780 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65  function, SQLite
27790 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20  .** allocates N 
277a0 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65  of memory, zeroe
277b0 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72  s out that memor
277c0 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  y, and returns a
277d0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
277e0 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e  he new memory. ^
277f0 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  On second and su
27800 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
27810 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67  o.** sqlite3_agg
27820 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
27830 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67   for the same ag
27840 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
27850 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68   instance,.** th
27860 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73  e same buffer is
27870 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69   returned.  Sqli
27880 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
27890 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61  ntext() is norma
278a0 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e  lly.** called on
278b0 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f  ce for each invo
278c0 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53  cation of the xS
278d0 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64  tep callback and
278e0 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73   then one.** las
278f0 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20  t time when the 
27900 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20  xFinal callback 
27910 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57  is invoked.  ^(W
27920 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63  hen no rows matc
27930 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74  h.** an aggregat
27940 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74  e query, the xSt
27950 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66  ep() callback of
27960 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66   the aggregate f
27970 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65  unction.** imple
27980 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76  mentation is nev
27990 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46  er called and xF
279a0 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64  inal() is called
279b0 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a   exactly once..*
279c0 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73  * In those cases
279d0 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  , sqlite3_aggreg
279e0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69  ate_context() mi
279f0 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f  ght be called fo
27a00 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  r the.** first t
27a10 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  ime from within 
27a20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a  xFinal().)^.**.*
27a30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61  * ^The sqlite3_a
27a40 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
27a50 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65  (C,N) routine re
27a60 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
27a70 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20  nter if N is.** 
27a80 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
27a90 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66  al to zero or if
27aa0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
27ab0 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  te error occurs.
27ac0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f  .**.** ^(The amo
27ad0 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c  unt of space all
27ae0 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
27af0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
27b00 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64  ext(C,N) is.** d
27b10 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
27b20 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20   N parameter on 
27b30 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c  first successful
27b40 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67   call.  Changing
27b50 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
27b60 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74   N in subsequent
27b70 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
27b80 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
27b90 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74  xt() within.** t
27ba0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
27bb0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
27bc0 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73  nce will not res
27bd0 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a  ize the memory.*
27be0 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a  * allocation.)^.
27bf0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75  **.** ^SQLite au
27c00 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
27c10 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
27c20 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71  ocated by .** sq
27c30 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27c40 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74  context() when t
27c50 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65  he aggregate que
27c60 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
27c70 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
27c80 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
27c90 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
27ca0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
27cb0 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
27cc0 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
27cd0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
27ce0 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
27cf0 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20  xStep or xFinal 
27d00 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
27d10 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
27d20 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
27d30 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
27d40 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
27d50 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
27d60 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
27d70 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
27d80 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
27d90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
27da0 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
27db0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
27dc0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
27dd0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
27de0 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
27df0 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
27e00 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
27e10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27e20 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20  te3_user_data() 
27e30 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27e40 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
27e50 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  he pointer that 
27e60 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74  was the pUserDat
27e70 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  a parameter (the
27e80 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a   5th parameter).
27e90 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
27ea0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
27eb0 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
27ec0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
27ed0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
27ee0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
27ef0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
27f00 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
27f10 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
27f20 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
27f30 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
27f40 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
27f50 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
27f60 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  ich.** the appli
27f70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
27f80 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
27f90 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
27fa0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
27fb0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
27fc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27fd0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
27fe0 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
27ff0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
28000 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
28010 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
28020 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
28030 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
28040 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
28050 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28060 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
28070 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
28080 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
28090 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
280a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
280b0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
280c0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
280d0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
280e0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
280f0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
28100 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73  d function..*/.s
28110 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
28120 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
28130 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
28140 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
28150 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
28160 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a  uxiliary Data.**
28170 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
28180 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  g two functions 
28190 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73  may be used by s
281a0 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
281b0 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
281c0 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
281d0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
281e0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
281f0 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
28200 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
28210 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
28220 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
28230 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
28240 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
28250 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
28260 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
28270 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
28280 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
28290 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
282a0 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
282b0 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
282c0 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
282d0 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
282e0 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
282f0 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
28300 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
28310 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
28320 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
28330 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
28340 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75  ith the SQL valu
28350 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
28360 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
28370 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20  on.** pattern.  
28380 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  The compiled reg
28390 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
283a0 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
283b0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
283c0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
283d0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f  same function so
283e0 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e   that the origin
283f0 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  al pattern strin
28400 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65  g.** does not ne
28410 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69  ed to be recompi
28420 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f  led on each invo
28430 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  cation..**.** ^T
28440 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
28450 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
28460 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
28470 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
28480 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
28490 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
284a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
284b0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
284c0 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
284d0 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
284e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
284f0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66  ed function. ^If
28500 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73   no metadata has
28510 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65   been ever.** be
28520 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e  en set for the N
28530 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  th argument of t
28540 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20  he function, or 
28550 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  if the correspon
28560 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ding.** function
28570 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63   parameter has c
28580 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65  hanged since the
28590 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73   meta-data was s
285a0 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  et,.** then sqli
285b0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
285c0 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
285d0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
285e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
285f0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
28600 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d  face saves the m
28610 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74  etadata.** point
28620 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64  ed to by its 3rd
28630 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
28640 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  e metadata for t
28650 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
28660 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
28670 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
28680 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71  unction.  Subseq
28690 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
286a0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
286b0 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74  data() might ret
286c0 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69  urn this data, i
286d0 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20  f it has.** not 
286e0 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a  been destroyed..
286f0 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74  ** ^If it is not
28700 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
28710 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
28720 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63  structor.** func
28730 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68  tion given by th
28740 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
28750 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
28760 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74  uxdata() on.** t
28770 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e  he metadata when
28780 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
28790 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
287a0 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a  meter changes.**
287b0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c   or when the SQL
287c0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c   statement compl
287d0 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20  etes, whichever 
287e0 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a  comes first..**.
287f0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
28800 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65  e to call the de
28810 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f  structor and dro
28820 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e  p metadata on an
28830 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
28840 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61  f any function a
28850 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68  t any time.  ^Th
28860 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65  e only guarantee
28870 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20   is that.** the 
28880 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20  destructor will 
28890 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65  be called before
288a0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
288b0 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20   dropped..**.** 
288c0 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  ^(In practice, m
288d0 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
288e0 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
288f0 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
28900 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
28910 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
28920 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
28930 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
28940 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
28950 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72  s and [parameter
28960 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  s].)^.**.** Thes
28970 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
28980 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
28990 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
289a0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
289b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
289c0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
289d0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
289e0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
289f0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76  text*, int N);.v
28a00 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
28a10 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
28a20 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
28a30 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
28a40 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
28a50 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
28a60 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
28a70 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
28a80 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
28a90 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
28aa0 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
28ab0 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
28ac0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
28ad0 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
28ae0 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
28af0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
28b00 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
28b10 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
28b20 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
28b30 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
28b40 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
28b50 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
28b60 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
28b70 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
28b80 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
28b90 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
28ba0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
28bb0 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
28bc0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
28bd0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
28be0 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
28bf0 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
28c00 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
28c10 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
28c20 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
28c30 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
28c40 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
28c50 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
28c60 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
28c70 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
28c80 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
28c90 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
28ca0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
28cb0 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
28cc0 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
28cd0 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
28ce0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
28cf0 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
28d00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
28d10 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
28d20 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
28d30 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
28d40 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
28d50 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
28d60 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
28d70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28d80 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
28d90 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
28da0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ction.**.** Thes
28db0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
28dc0 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
28dd0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
28de0 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
28df0 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
28e00 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
28e10 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
28e20 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
28e30 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
28e40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
28e50 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
28e60 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
28e70 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
28e80 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
28e90 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
28ea0 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74  ike the [paramet
28eb0 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69  er binding] fami
28ec0 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f  ly of.** functio
28ed0 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20  ns used to bind 
28ee0 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
28ef0 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
28f00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
28f10 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
28f20 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  e [SQL parameter
28f30 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
28f40 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
28f50 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
28f60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
28f70 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
28f80 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
28f90 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
28fa0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
28fb0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
28fc0 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
28fd0 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
28fe0 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
28ff0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
29000 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
29010 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
29020 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
29030 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
29040 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29050 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
29060 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
29070 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
29080 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
29090 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
290a0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
290b0 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
290c0 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
290d0 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
290e0 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
290f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
29100 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
29110 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
29120 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
29130 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
29140 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
29150 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
29160 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
29170 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
29180 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
29190 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
291a0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
291b0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
291c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
291d0 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
291e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
291f0 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
29200 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
29210 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
29220 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
29230 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e   exception..** ^
29240 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
29250 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
29260 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
29270 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
29280 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29290 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
292a0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
292b0 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
292c0 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
292d0 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74  ge.  ^SQLite int
292e0 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
292f0 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
29300 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
29310 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
29320 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74  as UTF-8. ^SQLit
29330 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
29340 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
29350 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29360 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
29370 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
29380 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66  byte order.  ^If
29390 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
293a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
293b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
293c0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
293d0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
293e0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
293f0 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
29400 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
29410 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
29420 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
29430 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
29440 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
29450 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
29460 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29470 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
29480 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
29490 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
294a0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
294b0 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
294c0 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
294d0 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
294e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
294f0 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
29500 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65  message..** ^The
29510 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
29520 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
29530 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
29540 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
29550 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
29560 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
29570 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
29580 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
29590 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
295a0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
295b0 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
295c0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
295d0 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
295e0 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
295f0 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20  t harm..** ^The 
29600 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
29610 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
29620 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
29630 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
29640 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
29650 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
29660 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
29670 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65  unction.  ^By de
29680 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
29690 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
296a0 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75  TE_ERROR.  ^A su
296b0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
296c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
296d0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
296e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
296f0 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
29700 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
29710 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
29720 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29730 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29  _result_toobig()
29740 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
29750 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
29760 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e  w an error.** in
29770 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
29780 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
29790 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  s too long to re
297a0 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  present..**.** ^
297b0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
297c0 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  lt_nomem() inter
297d0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
297e0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  te to throw an e
297f0 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69  rror.** indicati
29800 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
29810 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
29820 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
29830 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
29840 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
29850 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
29860 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
29870 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29880 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
29890 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
298a0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
298b0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
298c0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
298d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
298e0 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
298f0 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
29900 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
29910 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
29920 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29930 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
29940 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
29950 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
29960 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
29970 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
29980 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
29990 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
299a0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
299b0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
299c0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
299d0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
299e0 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
299f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29a00 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
29a10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
29a20 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
29a30 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
29a40 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
29a50 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
29a60 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
29a70 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
29a80 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
29a90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29aa0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
29ab0 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
29ac0 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
29ad0 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
29ae0 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
29af0 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
29b00 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
29b10 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
29b20 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
29b30 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69  tively..** ^SQLi
29b40 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78  te takes the tex
29b50 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68  t result from th
29b60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72  e application fr
29b70 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61  om.** the 2nd pa
29b80 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73  rameter of the s
29b90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
29ba0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  xt* interfaces..
29bb0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
29bc0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
29bd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
29be0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
29bf0 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
29c00 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
29c10 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72  s result text fr
29c20 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
29c30 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20  eter.** through 
29c40 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
29c50 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
29c60 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
29c70 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
29c80 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
29c90 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
29ca0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
29cb0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73  en as many bytes
29cc0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
29cd0 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a  ) of the text.**
29ce0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
29cf0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
29d00 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68   are taken as th
29d10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
29d20 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  fined.** functio
29d30 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  n result..** ^If
29d40 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
29d50 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
29d60 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
29d70 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
29d80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
29d90 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c  lob is a non-NUL
29da0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
29db0 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61  SQLite calls tha
29dc0 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73  t.** function as
29dd0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
29de0 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  on the text or B
29df0 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20  LOB result when 
29e00 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68  it has.** finish
29e10 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
29e20 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
29e30 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
29e40 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
29e50 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
29e60 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73  faces or to.** s
29e70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
29e80 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
29e90 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
29ea0 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53  E_STATIC, then S
29eb0 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73  QLite.** assumes
29ec0 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f   that the text o
29ed0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73  r BLOB result is
29ee0 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61   in constant spa
29ef0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a  ce and does not.
29f00 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74  ** copy the cont
29f10 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d  ent of the param
29f20 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20  eter nor call a 
29f30 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
29f40 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65  e content.** whe
29f50 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  n it has finishe
29f60 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
29f70 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
29f80 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
29f90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
29fa0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
29fb0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
29fc0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
29fd0 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
29fe0 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52  nstant SQLITE_TR
29ff0 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20  ANSIENT.** then 
2a000 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
2a010 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c  opy of the resul
2a020 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74  t into space obt
2a030 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72  ained from.** fr
2a040 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
2a050 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20  oc()] before it 
2a060 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2a070 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2a080 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
2a090 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2a0a0 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61  sult of.** the a
2a0b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a0c0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2a0d0 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20  e a copy the.** 
2a0e0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2a0f0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2a100 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ct specified by 
2a110 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2a120 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  r.  ^The.** sqli
2a130 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2a140 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  () interface mak
2a150 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
2a160 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2a170 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20  .** so that the 
2a180 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2a190 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
2a1a0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63   parameter may c
2a1b0 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64  hange or.** be d
2a1c0 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72  eallocated after
2a1d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2a1e0 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20  value() returns 
2a1f0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
2a200 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73   ^A [protected s
2a210 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2a220 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20  ject may always 
2a230 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e  be used where an
2a240 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
2a250 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2a260 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72  object is requir
2a270 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a  ed, so either.**
2a280 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65   kind of [sqlite
2a290 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2a2a0 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68  can be used with
2a2b0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e   this interface.
2a2c0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20  .**.** If these 
2a2d0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2a2e0 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20  led from within 
2a2f0 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68  the different th
2a300 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65  read.** than the
2a310 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20   one containing 
2a320 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2a330 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2a340 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a   that received.*
2a350 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  * the [sqlite3_c
2a360 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c  ontext] pointer,
2a370 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2a380 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76   undefined..*/.v
2a390 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2a3a0 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
2a3b0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2a3c0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2a3d0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2a3e0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2a3f0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2a400 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65  context*, double
2a410 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2a420 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
2a430 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2a440 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
2a450 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2a460 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
2a470 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2a480 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2a490 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
2a4a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
2a4b0 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
2a4c0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
2a4d0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2a4e0 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63  _nomem(sqlite3_c
2a4f0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
2a500 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2a510 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33  ror_code(sqlite3
2a520 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
2a530 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2a540 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
2a550 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
2a560 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2a570 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74  sult_int64(sqlit
2a580 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
2a590 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69  ite3_int64);.voi
2a5a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2a5b0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f  _null(sqlite3_co
2a5c0 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
2a5d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2a5e0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2a5f0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
2a600 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
2a610 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2a620 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2a630 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
2a640 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2a650 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
2a660 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2a670 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2a680 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
2a690 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2a6a0 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
2a6b0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
2a6c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2a6d0 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
2a6e0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2a6f0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
2a700 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
2a710 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2a720 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
2a730 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
2a740 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
2a750 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
2a760 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
2a770 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  xt*, int n);../*
2a780 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2a790 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69  fine New Collati
2a7a0 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a  ng Sequences.**.
2a7b0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
2a7c0 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ns are used to a
2a7d0 64 64 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  dd new collation
2a7e0 20 73 65 71 75 65 6e 63 65 73 20 74 6f 20 74 68   sequences to th
2a7f0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
2a800 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
2a810 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
2a820 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
2a830 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2a840 68 65 20 6e 65 77 20 63 6f 6c 6c 61 74 69 6f 6e  he new collation
2a850 20 73 65 71 75 65 6e 63 65 20 69 73 20 73 70 65   sequence is spe
2a860 63 69 66 69 65 64 20 61 73 20 61 20 55 54 46 2d  cified as a UTF-
2a870 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
2a880 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2a890 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
2a8a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2a8b0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
2a8c0 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
2a8d0 69 6e 67 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  ing for sqlite3_
2a8e0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2a8f0 31 36 28 29 2e 20 5e 49 6e 20 61 6c 6c 20 63 61  16(). ^In all ca
2a900 73 65 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  ses.** the name 
2a910 69 73 20 70 61 73 73 65 64 20 61 73 20 74 68 65  is passed as the
2a920 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e   second function
2a930 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2a940 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
2a950 6d 65 6e 74 20 6d 61 79 20 62 65 20 6f 6e 65 20  ment may be one 
2a960 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
2a970 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a   [SQLITE_UTF8],.
2a980 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ** [SQLITE_UTF16
2a990 4c 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LE], or [SQLITE_
2a9a0 55 54 46 31 36 42 45 5d 2c 20 69 6e 64 69 63 61  UTF16BE], indica
2a9b0 74 69 6e 67 20 74 68 61 74 20 74 68 65 20 75 73  ting that the us
2a9c0 65 72 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 72  er-supplied.** r
2a9d0 6f 75 74 69 6e 65 20 65 78 70 65 63 74 73 20 74  outine expects t
2a9e0 6f 20 62 65 20 70 61 73 73 65 64 20 70 6f 69 6e  o be passed poin
2a9f0 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
2aa00 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
2aa10 46 2d 38 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  F-8,.** UTF-16 l
2aa20 69 74 74 6c 65 2d 65 6e 64 69 61 6e 2c 20 6f 72  ittle-endian, or
2aa30 20 55 54 46 2d 31 36 20 62 69 67 2d 65 6e 64 69   UTF-16 big-endi
2aa40 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
2aa50 2e 20 5e 54 68 65 0a 2a 2a 20 74 68 69 72 64 20  . ^The.** third 
2aa60 61 72 67 75 6d 65 6e 74 20 6d 69 67 68 74 20 61  argument might a
2aa70 6c 73 6f 20 62 65 20 5b 53 51 4c 49 54 45 5f 55  lso be [SQLITE_U
2aa80 54 46 31 36 5d 20 74 6f 20 69 6e 64 69 63 61 74  TF16] to indicat
2aa90 65 20 74 68 61 74 20 74 68 65 20 72 6f 75 74 69  e that the routi
2aaa0 6e 65 0a 2a 2a 20 65 78 70 65 63 74 73 20 70 6f  ne.** expects po
2aab0 69 6e 74 65 72 73 20 74 6f 20 62 65 20 55 54 46  inters to be UTF
2aac0 2d 31 36 20 73 74 72 69 6e 67 73 20 69 6e 20 74  -16 strings in t
2aad0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
2aae0 72 64 65 72 2c 20 6f 72 20 74 68 65 0a 2a 2a 20  rder, or the.** 
2aaf0 61 72 67 75 6d 65 6e 74 20 63 61 6e 20 62 65 20  argument can be 
2ab00 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
2ab10 49 47 4e 45 44 5d 20 69 66 20 74 68 65 0a 2a 2a  IGNED] if the.**
2ab20 20 74 68 65 20 72 6f 75 74 69 6e 65 20 65 78 70   the routine exp
2ab30 65 63 74 73 20 70 6f 69 6e 74 65 72 73 20 74 6f  ects pointers to
2ab40 20 31 36 2d 62 69 74 20 77 6f 72 64 20 61 6c 69   16-bit word ali
2ab50 67 6e 65 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  gned strings.** 
2ab60 6f 66 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  of UTF-16 in the
2ab70 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2ab80 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e  er..**.** A poin
2ab90 74 65 72 20 74 6f 20 74 68 65 20 75 73 65 72 20  ter to the user 
2aba0 73 75 70 70 6c 69 65 64 20 72 6f 75 74 69 6e 65  supplied routine
2abb0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
2abc0 61 73 20 74 68 65 20 66 69 66 74 68 0a 2a 2a 20  as the fifth.** 
2abd0 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 69  argument.  ^If i
2abe0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 69 73 20  t is NULL, this 
2abf0 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 64  is the same as d
2ac00 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6c 6c  eleting the coll
2ac10 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
2ac20 65 20 28 73 6f 20 74 68 61 74 20 53 51 4c 69 74  e (so that SQLit
2ac30 65 20 63 61 6e 6e 6f 74 20 63 61 6c 6c 20 69 74  e cannot call it
2ac40 20 61 6e 79 6d 6f 72 65 29 2e 0a 2a 2a 20 5e 45   anymore)..** ^E
2ac50 61 63 68 20 74 69 6d 65 20 74 68 65 20 61 70 70  ach time the app
2ac60 6c 69 63 61 74 69 6f 6e 20 73 75 70 70 6c 69 65  lication supplie
2ac70 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  d function is in
2ac80 76 6f 6b 65 64 2c 20 69 74 20 69 73 20 70 61 73  voked, it is pas
2ac90 73 65 64 0a 2a 2a 20 61 73 20 69 74 73 20 66 69  sed.** as its fi
2aca0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 61 20  rst parameter a 
2acb0 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
2acc0 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  * passed as the 
2acd0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a  fourth argument.
2ace0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  ** to sqlite3_cr
2acf0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2ad00 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61   or sqlite3_crea
2ad10 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
2ad20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 6d  ..**.** ^The rem
2ad30 61 69 6e 69 6e 67 20 61 72 67 75 6d 65 6e 74 73  aining arguments
2ad40 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
2ad50 69 6f 6e 2d 73 75 70 70 6c 69 65 64 20 72 6f 75  ion-supplied rou
2ad60 74 69 6e 65 20 61 72 65 20 74 77 6f 20 73 74 72  tine are two str
2ad70 69 6e 67 73 2c 0a 2a 2a 20 65 61 63 68 20 72 65  ings,.** each re
2ad80 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 28  presented by a (
2ad90 6c 65 6e 67 74 68 2c 20 64 61 74 61 29 20 70 61  length, data) pa
2ada0 69 72 20 61 6e 64 20 65 6e 63 6f 64 65 64 20 69  ir and encoded i
2adb0 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 0a 2a  n the encoding.*
2adc0 2a 20 74 68 61 74 20 77 61 73 20 70 61 73 73 65  * that was passe
2add0 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61  d as the third a
2ade0 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 74 68 65  rgument when the
2adf0 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
2ae00 6e 63 65 20 77 61 73 0a 2a 2a 20 72 65 67 69 73  nce was.** regis
2ae10 74 65 72 65 64 2e 20 20 54 68 65 20 61 70 70 6c  tered.  The appl
2ae20 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2ae30 63 6f 6c 6c 61 74 69 6f 6e 20 72 6f 75 74 69 6e  collation routin
2ae40 65 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  e should.** retu
2ae50 72 6e 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  rn negative, zer
2ae60 6f 20 6f 72 20 70 6f 73 69 74 69 76 65 20 69 66  o or positive if
2ae70 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
2ae80 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 0a  g is less than,.
2ae90 2a 2a 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20  ** equal to, or 
2aea0 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65  greater than the
2aeb0 20 73 65 63 6f 6e 64 20 73 74 72 69 6e 67 2e 20   second string. 
2aec0 69 2e 65 2e 20 28 53 54 52 49 4e 47 31 20 2d 20  i.e. (STRING1 - 
2aed0 53 54 52 49 4e 47 32 29 2e 0a 2a 2a 0a 2a 2a 20  STRING2)..**.** 
2aee0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
2aef0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2af00 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
2af10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2af20 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 65 78 63 65  lation().** exce
2af30 70 74 20 74 68 61 74 20 69 74 20 74 61 6b 65 73  pt that it takes
2af40 20 61 6e 20 65 78 74 72 61 20 61 72 67 75 6d 65   an extra argume
2af50 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 64 65  nt which is a de
2af60 73 74 72 75 63 74 6f 72 20 66 6f 72 0a 2a 2a 20  structor for.** 
2af70 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 2e 20 20  the collation.  
2af80 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
2af90 69 73 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  is called when t
2afa0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 0a  he collation is.
2afb0 2a 2a 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64  ** destroyed and
2afc0 20 69 73 20 70 61 73 73 65 64 20 61 20 63 6f 70   is passed a cop
2afd0 79 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  y of the fourth 
2afe0 70 61 72 61 6d 65 74 65 72 20 76 6f 69 64 2a 20  parameter void* 
2aff0 70 6f 69 6e 74 65 72 0a 2a 2a 20 6f 66 20 74 68  pointer.** of th
2b000 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2b010 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 2e  _collation_v2().
2b020 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 73 20  .** ^Collations 
2b030 61 72 65 20 64 65 73 74 72 6f 79 65 64 20 77 68  are destroyed wh
2b040 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  en they are over
2b050 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 20  ridden by later 
2b060 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
2b070 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
2b080 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  on functions or 
2b090 77 68 65 6e 20 74 68 65 20 5b 64 61 74 61 62 61  when the [databa
2b0a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2b0b0 73 20 63 6c 6f 73 65 64 0a 2a 2a 20 75 73 69 6e  s closed.** usin
2b0c0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
2b0d0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2b0e0 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63  lso:  [sqlite3_c
2b0f0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2b100 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2b110 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2b120 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
2b130 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2b140 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
2b150 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
2b160 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
2b170 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
2b180 69 64 2a 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  id*,.  int(*xCom
2b190 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
2b1a0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
2b1b0 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
2b1c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2b1d0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2b1e0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2b1f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2b200 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2b210 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  ep, .  void*,.  
2b220 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2b230 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2b240 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2b250 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
2b260 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
2b270 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2b280 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2b290 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
2b2a0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
2b2b0 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
2b2c0 52 65 70 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20  Rep, .  void*,. 
2b2d0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
2b2e0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2b2f0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
2b300 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
2b310 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
2b320 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
2b330 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20  backs.**.** ^To 
2b340 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
2b350 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
2b360 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
2b370 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
2b380 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
2b390 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
2b3a0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
2b3b0 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
2b3c0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74  with the.** [dat
2b3d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2b3e0 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  ] to be invoked 
2b3f0 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
2b400 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
2b410 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
2b420 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
2b430 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
2b440 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
2b450 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2b460 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2b470 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
2b480 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
2b490 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
2b4a0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
2b4b0 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
2b4c0 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
2b4d0 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69   UTF-8. ^If sqli
2b4e0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2b4f0 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
2b500 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61  ,.** the names a
2b510 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
2b520 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
2b530 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
2b540 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
2b550 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
2b560 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69  replaces the exi
2b570 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d  sting collation-
2b580 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e  needed callback.
2b590 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68  .**.** ^(When th
2b5a0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
2b5b0 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
2b5c0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
2b5d0 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
2b5e0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
2b5f0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2b600 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2b610 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
2b620 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
2b630 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
2b640 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2b650 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
2b660 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
2b670 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
2b680 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
2b690 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
2b6a0 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20  UTF16BE],.** or 
2b6b0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2b6c0 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
2b6d0 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20   most desirable 
2b6e0 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c  form of the coll
2b6f0 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
2b700 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
2b710 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68  red.  The fourth
2b720 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2b730 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
2b740 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74   required collat
2b750 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a  ion sequence.)^.
2b760 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
2b770 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
2b780 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
2b790 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
2b7a0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
2b7b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2b7c0 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
2b7d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2b7e0 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
2b7f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2b800 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
2b810 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2b820 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
2b830 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2b840 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
2b850 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
2b860 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
2b870 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e  nst char*).);.in
2b880 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
2b890 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
2b8a0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
2b8b0 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
2b8c0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
2b8d0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
2b8e0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65  void*).);..#ifde
2b8f0 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44  f SQLITE_HAS_COD
2b900 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  EC./*.** Specify
2b910 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
2b920 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
2b930 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
2b940 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
2b950 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
2b960 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
2b970 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
2b980 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2b990 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
2b9a0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
2b9b0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
2b9c0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
2b9d0 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
2b9e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2b9f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ba00 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
2ba10 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
2ba20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
2ba30 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
2ba40 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
2ba50 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
2ba60 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
2ba70 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
2ba80 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
2ba90 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
2baa0 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
2bab0 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
2bac0 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
2bad0 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
2bae0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
2baf0 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
2bb00 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
2bb10 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
2bb20 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
2bb30 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
2bb40 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
2bb50 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
2bb60 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
2bb70 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2bb80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2bb90 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
2bba0 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
2bbb0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
2bbc0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
2bbd0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
2bbe0 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
2bbf0 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
2bc00 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74  ey for a SEE dat
2bc10 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
2bc20 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
2bc30 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f  ne of the SEE ro
2bc40 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
2bc50 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
2bc60 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a  3_activate_see(.
2bc70 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
2bc80 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
2bc90 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
2bca0 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
2bcb0 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  if..#ifdef SQLIT
2bcc0 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f  E_ENABLE_CEROD./
2bcd0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
2bce0 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
2bcf0 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61  for a CEROD data
2bd00 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
2bd10 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
2bd20 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72  e of the CEROD r
2bd30 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
2bd40 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
2bd50 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f  e3_activate_cero
2bd60 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  d(.  const char 
2bd70 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
2bd80 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
2bd90 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
2bda0 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2bdb0 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
2bdc0 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
2bdd0 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20  hort Time.**.** 
2bde0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65  ^The sqlite3_sle
2bdf0 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61  ep() function ca
2be00 75 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74  uses the current
2be10 20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65   thread to suspe
2be20 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20  nd execution.** 
2be30 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e  for at least a n
2be40 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
2be50 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20  conds specified 
2be60 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  in its parameter
2be70 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2be80 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
2be90 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72   does not suppor
2bea0 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74 73  t sleep requests
2beb0 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65   with.** millise
2bec0 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75  cond time resolu
2bed0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74  tion, then the t
2bee0 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e  ime will be roun
2bef0 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65  ded up to.** the
2bf00 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e   nearest second.
2bf10 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
2bf20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
2bf30 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a  sleep actually.*
2bf40 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
2bf50 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
2bf60 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
2bf70 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
2bf80 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73   implements this
2bf90 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61   interface by ca
2bfa0 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70  lling the xSleep
2bfb0 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ().** method of 
2bfc0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
2bfd0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
2bfe0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2bff0 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a  _sleep(int);../*
2c000 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
2c010 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
2c020 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61   Holding Tempora
2c030 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  ry Files.**.** ^
2c040 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
2c050 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
2c060 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
2c070 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
2c080 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
2c090 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
2c0a0 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
2c0b0 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69  all temporary fi
2c0c0 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  les.** created b
2c0d0 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73  y SQLite when us
2c0e0 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b  ing a built-in [
2c0f0 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46  sqlite3_vfs | VF
2c100 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c  S].** will be pl
2c110 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72  aced in that dir
2c120 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74  ectory.)^  ^If t
2c130 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
2c140 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2c150 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70  r, then SQLite p
2c160 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68  erforms a search
2c170 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69   for an appropri
2c180 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  ate.** temporary
2c190 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e   file directory.
2c1a0 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  .**.** It is not
2c1b0 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
2c1c0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
2c1d0 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68  iable in more th
2c1e0 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64  an one.** thread
2c1f0 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20   at a time.  It 
2c200 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
2c210 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
2c220 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2c230 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  f a [database co
2c240 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
2c250 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73  ng used at the s
2c260 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65  ame time in a se
2c270 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64  parate.** thread
2c280 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e  ..** It is inten
2c290 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61  ded that this va
2c2a0 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e  riable be set on
2c2b0 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ce.** as part of
2c2c0 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
2c2d0 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f  ization and befo
2c2e0 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  re any SQLite in
2c2f0 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69  terface.** routi
2c300 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61  nes have been ca
2c310 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68  lled and that th
2c320 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61  is variable rema
2c330 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20  in unchanged.** 
2c340 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a  thereafter..**.*
2c350 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f  * ^The [temp_sto
2c360 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
2c370 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20  gma] may modify 
2c380 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e  this variable an
2c390 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f  d cause.** it to
2c3a0 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
2c3b0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
2c3c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e  sqlite3_malloc].
2c3d0 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a    ^Furthermore,.
2c3e0 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  ** the [temp_sto
2c3f0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
2c400 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75  gma] always assu
2c410 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72  mes that any str
2c420 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73  ing.** that this
2c430 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73   variable points
2c440 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d   to is held in m
2c450 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
2c460 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
2c470 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65  _malloc] and the
2c480 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65   pragma may atte
2c490 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74  mpt to free that
2c4a0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67   memory.** using
2c4b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e   [sqlite3_free].
2c4c0 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68  .** Hence, if th
2c4d0 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  is variable is m
2c4e0 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79  odified directly
2c4f0 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75  , either it shou
2c500 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55  ld be.** made NU
2c510 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f  LL or made to po
2c520 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  int to memory ob
2c530 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2c540 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20  ite3_malloc].** 
2c550 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20  or else the use 
2c560 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f  of the [temp_sto
2c570 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
2c580 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61  gma] should be a
2c590 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  voided..*/.SQLIT
2c5a0 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73  E_EXTERN char *s
2c5b0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65  qlite3_temp_dire
2c5c0 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ctory;../*.** CA
2c5d0 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72  PI3REF: Test For
2c5e0 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64   Auto-Commit Mod
2c5f0 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  e.** KEYWORDS: {
2c600 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d  autocommit mode}
2c610 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c620 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
2c630 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  it() interface r
2c640 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20  eturns non-zero 
2c650 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68  or.** zero if th
2c660 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65  e given database
2c670 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
2c680 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f  r is not in auto
2c690 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20  commit mode,.** 
2c6a0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e  respectively.  ^
2c6b0 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
2c6c0 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  is on by default
2c6d0 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74  ..** ^Autocommit
2c6e0 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65   mode is disable
2c6f0 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73  d by a [BEGIN] s
2c700 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75  tatement..** ^Au
2c710 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73  tocommit mode is
2c720 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61   re-enabled by a
2c730 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f   [COMMIT] or [RO
2c740 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49  LLBACK]..**.** I
2c750 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20  f certain kinds 
2c760 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20  of errors occur 
2c770 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77  on a statement w
2c780 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74  ithin a multi-st
2c790 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73  atement.** trans
2c7a0 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69  action (errors i
2c7b0 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45  ncluding [SQLITE
2c7c0 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f  _FULL], [SQLITE_
2c7d0 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  IOERR],.** [SQLI
2c7e0 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49  TE_NOMEM], [SQLI
2c7f0 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53  TE_BUSY], and [S
2c800 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
2c810 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72  ) then the.** tr
2c820 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20  ansaction might 
2c830 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
2c840 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54  utomatically.  T
2c850 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a  he only way to.*
2c860 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68  * find out wheth
2c870 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  er SQLite automa
2c880 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
2c890 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2c8a0 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20  ion after.** an 
2c8b0 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20  error is to use 
2c8c0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
2c8d0 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20  *.** If another 
2c8e0 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74  thread changes t
2c8f0 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74  he autocommit st
2c900 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61  atus of the data
2c910 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
2c920 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f  on while this ro
2c930 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67  utine is running
2c940 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  , then the retur
2c950 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e  n value.** is un
2c960 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20  defined..*/.int 
2c970 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
2c980 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29  commit(sqlite3*)
2c990 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c9a0 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61  F: Find The Data
2c9b0 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41  base Handle Of A
2c9c0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2c9d0 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ent.**.** ^The s
2c9e0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
2c9f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2ca00 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ns the [database
2ca10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
2ca20 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20  dle.** to which 
2ca30 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2ca40 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20  ement] belongs. 
2ca50 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20   ^The [database 
2ca60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72  connection].** r
2ca70 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2ca80 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20  e3_db_handle is 
2ca90 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
2caa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
2cab0 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66  * that was the f
2cac0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
2cad0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2cae0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63  _prepare_v2()] c
2caf0 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69  all (or its vari
2cb00 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75  ants) that was u
2cb10 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65  sed to.** create
2cb20 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2cb30 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
2cb40 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73  e..*/.sqlite3 *s
2cb50 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
2cb60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2cb70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cb80 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
2cb90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cba0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  nt.**.** ^This i
2cbb0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2cbc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2cbd0 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64  e next [prepared
2cbe0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65   statement] afte
2cbf0 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63  r.** pStmt assoc
2cc00 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
2cc10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc20 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70  ion] pDb.  ^If p
2cc30 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
2cc40 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
2cc50 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2cc60 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
2cc70 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
2cc80 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
2cc90 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
2cca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ccb0 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72   pDb.  ^If no pr
2ccc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ccd0 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68  .** satisfies th
2cce0 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20  e conditions of 
2ccf0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74  this routine, it
2cd00 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
2cd10 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61  *.** The [databa
2cd20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
2cd30 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
2cd40 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2cd50 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29  3_next_stmt(D,S)
2cd60 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20  ] must refer to 
2cd70 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
2cd80 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  .** connection a
2cd90 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
2cda0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
2cdb0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
2cdc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71  sqlite3_stmt *sq
2cdd0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
2cde0 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71  sqlite3 *pDb, sq
2cdf0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2ce00 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2ce10 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
2ce20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
2ce30 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
2ce40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ce50 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
2ce60 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
2ce70 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
2ce80 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
2ce90 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
2cea0 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
2ceb0 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f   is [COMMIT | co
2cec0 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e  mmitted]..** ^An
2ced0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2cee0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2cef0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
2cf00 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
2cf10 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
2cf20 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2cf30 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
2cf40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f   ^The sqlite3_ro
2cf50 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e  llback_hook() in
2cf60 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
2cf70 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
2cf80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
2cf90 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
2cfa0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
2cfb0 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c   [ROLLBACK | rol
2cfc0 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41  led back]..** ^A
2cfd0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
2cfe0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
2cff0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f  ll to sqlite3_ro
2d000 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a  llback_hook().**
2d010 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
2d020 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d030 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
2d040 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72  .** ^The pArg ar
2d050 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64  gument is passed
2d060 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
2d070 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66  callback..** ^If
2d080 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e   the callback on
2d090 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66   a commit hook f
2d0a0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
2d0b0 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65  non-zero,.** the
2d0c0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20  n the commit is 
2d0d0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
2d0e0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
2d0f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
2d100 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  mmit_hook(D,C,P)
2d110 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c   and sqlite3_rol
2d120 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50  lback_hook(D,C,P
2d130 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72  ) functions.** r
2d140 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75  eturn the P argu
2d150 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
2d160 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74  evious call of t
2d170 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2d180 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
2d190 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2d1a0 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
2d1b0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73   for.** the firs
2d1c0 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20  t call for each 
2d1d0 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a  function on D..*
2d1e0 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
2d1f0 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  k implementation
2d200 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
2d210 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
2d220 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
2d230 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2d240 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
2d250 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e  he callback.  An
2d260 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
2d270 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2d280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2d290 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
2d2a0 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
2d2b0 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
2d2c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2d2d0 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
2d2e0 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f  triggered the co
2d2f0 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62  mmit.** or rollb
2d300 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20  ack hook in the 
2d310 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20  first place..** 
2d320 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
2d330 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2d340 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
2d350 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
2d360 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
2d370 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
2d380 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
2d390 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
2d3a0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
2d3b0 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e  *.** ^Registerin
2d3c0 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f  g a NULL functio
2d3d0 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  n disables the c
2d3e0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
2d3f0 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  When the commit 
2d400 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f  hook callback ro
2d410 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65  utine returns ze
2d420 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d  ro, the [COMMIT]
2d430 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  .** operation is
2d440 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74   allowed to cont
2d450 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20  inue normally.  
2d460 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  ^If the commit h
2d470 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e  ook.** returns n
2d480 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
2d490 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f  e [COMMIT] is co
2d4a0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b  nverted into a [
2d4b0 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54  ROLLBACK]..** ^T
2d4c0 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b  he rollback hook
2d4d0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
2d4e0 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72   rollback that r
2d4f0 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f  esults from a co
2d500 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74  mmit.** hook ret
2d510 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c  urning non-zero,
2d520 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c   just as it woul
2d530 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74  d be with any ot
2d540 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  her rollback..**
2d550 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
2d560 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50  poses of this AP
2d570 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  I, a transaction
2d580 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65   is said to have
2d590 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20   been.** rolled 
2d5a0 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69  back if an expli
2d5b0 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73  cit "ROLLBACK" s
2d5c0 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63  tatement is exec
2d5d0 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65  uted, or.** an e
2d5e0 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69  rror or constrai
2d5f0 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70  nt causes an imp
2d600 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74  licit rollback t
2d610 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65  o occur..** ^The
2d620 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61   rollback callba
2d630 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ck is not invoke
2d640 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69  d if a transacti
2d650 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74  on is.** automat
2d660 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2d670 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64  ck because the d
2d680 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d690 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a  on is closed..**
2d6a0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
2d6b0 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65   [sqlite3_update
2d6c0 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61  _hook()] interfa
2d6d0 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ce..*/.void *sql
2d6e0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2d6f0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
2d700 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
2d710 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
2d720 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71  rollback_hook(sq
2d730 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28  lite3*, void(*)(
2d740 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b  void *), void*);
2d750 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d760 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f  : Data Change No
2d770 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
2d780 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
2d790 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68  sqlite3_update_h
2d7a0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
2d7b0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
2d7c0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
2d7d0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
2d7e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2d7f0 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
2d800 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2d810 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  .** to be invoke
2d820 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77  d whenever a row
2d830 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73   is updated, ins
2d840 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
2d850 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
2d860 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
2d870 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
2d880 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f  s function.** fo
2d890 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
2d8a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2d8b0 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
2d8c0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2d8d0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2d8e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e  inter to the fun
2d8f0 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20  ction to invoke 
2d900 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73  when a.** row is
2d910 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
2d920 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
2d930 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2d940 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c  ument to the cal
2d950 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20  lback is a copy 
2d960 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67  of the third arg
2d970 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69  ument.** to sqli
2d980 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
2d990 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  )..** ^The secon
2d9a0 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d  d callback argum
2d9b0 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
2d9c0 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b  QLITE_INSERT], [
2d9d0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a  SQLITE_DELETE],.
2d9e0 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50  ** or [SQLITE_UP
2d9f0 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67  DATE], depending
2da00 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f   on the operatio
2da10 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68  n that caused th
2da20 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f  e callback.** to
2da30 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20   be invoked..** 
2da40 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66  ^The third and f
2da50 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20  ourth arguments 
2da60 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
2da70 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73  contain pointers
2da80 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
2da90 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61  ase and table na
2daa0 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  me containing th
2dab0 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a  e affected row..
2dac0 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61  ** ^The final ca
2dad0 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72  llback parameter
2dae0 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20   is the [rowid] 
2daf0 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e  of the row..** ^
2db00 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61  In the case of a
2db10 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69  n update, this i
2db20 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66  s the [rowid] af
2db30 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74  ter the update t
2db40 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a  akes place..**.*
2db50 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68  * ^(The update h
2db60 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ook is not invok
2db70 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c  ed when internal
2db80 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61   system tables a
2db90 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28  re.** modified (
2dba0 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74  i.e. sqlite_mast
2dbb0 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65  er and sqlite_se
2dbc0 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a  quence).)^.**.**
2dbd0 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74   ^In the current
2dbe0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c   implementation,
2dbf0 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   the update hook
2dc00 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  .** is not invok
2dc10 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74  ed when duplicat
2dc20 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c  ion rows are del
2dc30 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20  eted because of 
2dc40 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49  an.** [ON CONFLI
2dc50 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54  CT | ON CONFLICT
2dc60 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65   REPLACE] clause
2dc70 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75  .  ^Nor is the u
2dc80 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e  pdate hook.** in
2dc90 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20  voked when rows 
2dca0 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e  are deleted usin
2dcb0 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20  g the [truncate 
2dcc0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a  optimization]..*
2dcd0 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73  * The exceptions
2dce0 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73   defined in this
2dcf0 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74   paragraph might
2dd00 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
2dd10 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
2dd20 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
2dd30 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
2dd40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
2dd50 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
2dd60 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
2dd70 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
2dd80 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2dd90 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
2dda0 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41   update hook.  A
2ddb0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
2ddc0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2ddd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2dde0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
2ddf0 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
2de00 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
2de10 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
2de20 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
2de30 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75   triggered the u
2de40 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e  pdate hook..** N
2de50 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
2de60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2de70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
2de80 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
2de90 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
2dea0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
2deb0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
2dec0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
2ded0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
2dee0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2def0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43  _update_hook(D,C
2df00 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ,P) function.** 
2df10 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72  returns the P ar
2df20 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20  gument from the 
2df30 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a  previous call.**
2df40 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61   on the same [da
2df50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2df60 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f  n] D, or NULL fo
2df70 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63  r.** the first c
2df80 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  all on D..**.** 
2df90 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
2dfa0 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
2dfb0 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  k()] and [sqlite
2dfc0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
2dfd0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  )].** interfaces
2dfe0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2dff0 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a  e3_update_hook(.
2e000 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
2e010 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e  oid(*)(void *,in
2e020 74 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c  t ,char const *,
2e030 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c  char const *,sql
2e040 69 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76  ite3_int64),.  v
2e050 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  oid*.);../*.** C
2e060 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
2e070 4f 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65  Or Disable Share
2e080 64 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a  d Pager Cache.**
2e090 20 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72   KEYWORDS: {shar
2e0a0 65 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20  ed cache}.**.** 
2e0b0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65  ^(This routine e
2e0c0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
2e0d0 65 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f  es the sharing o
2e0e0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
2e0f0 61 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65  ache.** and sche
2e100 6d 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ma data structur
2e110 65 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61  es between [data
2e120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2e130 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a  | connections].*
2e140 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61  * to the same da
2e150 74 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20  tabase. Sharing 
2e160 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68  is enabled if th
2e170 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72  e argument is tr
2e180 75 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c  ue.** and disabl
2e190 65 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65  ed if the argume
2e1a0 6e 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a  nt is false.)^.*
2e1b0 2a 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72  *.** ^Cache shar
2e1c0 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61  ing is enabled a
2e1d0 6e 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20  nd disabled for 
2e1e0 61 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73  an entire proces
2e1f0 73 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  s..** This is a 
2e200 63 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c  change as of SQL
2e210 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
2e220 30 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73  0. In prior vers
2e230 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a  ions of SQLite,.
2e240 2a 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65  ** sharing was e
2e250 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
2e260 65 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65  ed for each thre
2e270 61 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  ad separately..*
2e280 2a 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65  *.** ^(The cache
2e290 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65   sharing mode se
2e2a0 74 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66  t by this interf
2e2b0 61 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20  ace effects all 
2e2c0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  subsequent.** ca
2e2d0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2e2e0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2e2f0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
2e300 64 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  d [sqlite3_open1
2e310 36 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  6()]..** Existin
2e320 67 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  g database conne
2e330 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
2e340 75 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20  use the sharing 
2e350 6d 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73  mode.** that was
2e360 20 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68   in effect at th
2e370 65 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65  e time they were
2e380 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a   opened.)^.**.**
2e390 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2e3a0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2e3b0 4f 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61  OK] if shared ca
2e3c0 63 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20  che was enabled 
2e3d0 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73  or disabled.** s
2e3e0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e  uccessfully.  An
2e3f0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
2e400 20 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77   returned otherw
2e410 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68  ise.)^.**.** ^Sh
2e420 61 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69  ared cache is di
2e430 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
2e440 74 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68  t. But this migh
2e450 74 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66  t change in.** f
2e460 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
2e470 66 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69  f SQLite.  Appli
2e480 63 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72  cations that car
2e490 65 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a  e about shared.*
2e4a0 2a 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20  * cache setting 
2e4b0 73 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78  should set it ex
2e4c0 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20  plicitly..**.** 
2e4d0 53 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69  See Also:  [SQLi
2e4e0 74 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20  te Shared-Cache 
2e4f0 4d 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Mode].*/.int sql
2e500 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
2e510 65 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a  ed_cache(int);..
2e520 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e530 41 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20  Attempt To Free 
2e540 48 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a  Heap Memory.**.*
2e550 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2e560 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
2e570 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
2e580 74 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74  ts to free N byt
2e590 65 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65  es.** of heap me
2e5a0 6d 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61  mory by dealloca
2e5b0 74 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69  ting non-essenti
2e5c0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
2e5d0 74 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79  tions.** held by
2e5e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69   the database li
2e5f0 62 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20  brary.   Memory 
2e600 75 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61  used to cache da
2e610 74 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20  tabase.** pages 
2e620 74 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  to improve perfo
2e630 72 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61  rmance is an exa
2e640 6d 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65  mple of non-esse
2e650 6e 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  ntial memory..**
2e660 20 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73   ^sqlite3_releas
2e670 65 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72  e_memory() retur
2e680 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2e690 20 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20   bytes actually 
2e6a0 66 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20  freed,.** which 
2e6b0 6d 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72  might be more or
2e6c0 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61   less than the a
2e6d0 6d 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e  mount requested.
2e6e0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e6f0 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 69  release_memory(i
2e700 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2e710 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c  3REF: Impose A L
2e720 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53 69 7a  imit On Heap Siz
2e730 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
2e740 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
2e750 69 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  imit() interface
2e760 20 70 6c 61 63 65 73 20 61 20 22 73 6f 66 74 22   places a "soft"
2e770 20 6c 69 6d 69 74 0a 2a 2a 20 6f 6e 20 74 68 65   limit.** on the
2e780 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70 20   amount of heap 
2e790 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79 20  memory that may 
2e7a0 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  be allocated by 
2e7b0 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 49 66 20 61  SQLite..** ^If a
2e7c0 6e 20 69 6e 74 65 72 6e 61 6c 20 61 6c 6c 6f 63  n internal alloc
2e7d0 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74  ation is request
2e7e0 65 64 20 74 68 61 74 20 77 6f 75 6c 64 20 65 78  ed that would ex
2e7f0 63 65 65 64 20 74 68 65 0a 2a 2a 20 73 6f 66 74  ceed the.** soft
2e800 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 5b 73 71   heap limit, [sq
2e810 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
2e820 6d 6f 72 79 28 29 5d 20 69 73 20 69 6e 76 6f 6b  mory()] is invok
2e830 65 64 20 6f 6e 65 20 6f 72 0a 2a 2a 20 6d 6f 72  ed one or.** mor
2e840 65 20 74 69 6d 65 73 20 74 6f 20 66 72 65 65 20  e times to free 
2e850 75 70 20 73 6f 6d 65 20 73 70 61 63 65 20 62 65  up some space be
2e860 66 6f 72 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  fore the allocat
2e870 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64  ion is performed
2e880 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6c 69 6d  ..**.** ^The lim
2e890 69 74 20 69 73 20 63 61 6c 6c 65 64 20 22 73 6f  it is called "so
2e8a0 66 74 22 20 62 65 63 61 75 73 65 20 69 66 20 5b  ft" because if [
2e8b0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2e8c0 6d 65 6d 6f 72 79 28 29 5d 0a 2a 2a 20 63 61 6e  memory()].** can
2e8d0 6e 6f 74 20 66 72 65 65 20 73 75 66 66 69 63 69  not free suffici
2e8e0 65 6e 74 20 6d 65 6d 6f 72 79 20 74 6f 20 70 72  ent memory to pr
2e8f0 65 76 65 6e 74 20 74 68 65 20 6c 69 6d 69 74 20  event the limit 
2e900 66 72 6f 6d 20 62 65 69 6e 67 20 65 78 63 65 65  from being excee
2e910 64 65 64 2c 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  ded,.** the memo
2e920 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20  ry is allocated 
2e930 61 6e 79 77 61 79 20 61 6e 64 20 74 68 65 20 63  anyway and the c
2e940 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
2e950 20 70 72 6f 63 65 65 64 73 2e 0a 2a 2a 0a 2a 2a   proceeds..**.**
2e960 20 5e 41 20 6e 65 67 61 74 69 76 65 20 6f 72 20   ^A negative or 
2e970 7a 65 72 6f 20 76 61 6c 75 65 20 66 6f 72 20 4e  zero value for N
2e980 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 72   means that ther
2e990 65 20 69 73 20 6e 6f 20 73 6f 66 74 20 68 65 61  e is no soft hea
2e9a0 70 20 6c 69 6d 69 74 20 61 6e 64 0a 2a 2a 20 5b  p limit and.** [
2e9b0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
2e9c0 6d 65 6d 6f 72 79 28 29 5d 20 77 69 6c 6c 20 6f  memory()] will o
2e9d0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
2e9e0 65 6e 20 6d 65 6d 6f 72 79 20 69 73 20 65 78 68  en memory is exh
2e9f0 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  austed..** ^The 
2ea00 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f  default value fo
2ea10 72 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  r the soft heap 
2ea20 6c 69 6d 69 74 20 69 73 20 7a 65 72 6f 2e 0a 2a  limit is zero..*
2ea30 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 6d 61  *.** ^(SQLite ma
2ea40 6b 65 73 20 61 20 62 65 73 74 20 65 66 66 6f 72  kes a best effor
2ea50 74 20 74 6f 20 68 6f 6e 6f 72 20 74 68 65 20 73  t to honor the s
2ea60 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 0a  oft heap limit..
2ea70 2a 2a 20 42 75 74 20 69 66 20 74 68 65 20 73 6f  ** But if the so
2ea80 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
2ea90 6e 6e 6f 74 20 62 65 20 68 6f 6e 6f 72 65 64 2c  nnot be honored,
2eaa0 20 65 78 65 63 75 74 69 6f 6e 20 77 69 6c 6c 0a   execution will.
2eab0 2a 2a 20 63 6f 6e 74 69 6e 75 65 20 77 69 74 68  ** continue with
2eac0 6f 75 74 20 65 72 72 6f 72 20 6f 72 20 6e 6f 74  out error or not
2ead0 69 66 69 63 61 74 69 6f 6e 2e 29 5e 20 20 54 68  ification.)^  Th
2eae0 69 73 20 69 73 20 77 68 79 20 74 68 65 20 6c 69  is is why the li
2eaf0 6d 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64  mit is.** called
2eb00 20 61 20 22 73 6f 66 74 22 20 6c 69 6d 69 74 2e   a "soft" limit.
2eb10 20 20 49 74 20 69 73 20 61 64 76 69 73 6f 72 79    It is advisory
2eb20 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   only..**.** Pri
2eb30 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
2eb40 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 69 73  sion 3.5.0, this
2eb50 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 63 6f   routine only co
2eb60 6e 73 74 72 61 69 6e 65 64 20 74 68 65 20 6d 65  nstrained the me
2eb70 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  mory.** allocate
2eb80 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  d by a single th
2eb90 72 65 61 64 20 2d 20 74 68 65 20 73 61 6d 65 20  read - the same 
2eba0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 20  thread in which 
2ebb0 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  this routine.** 
2ebc0 72 75 6e 73 2e 20 20 42 65 67 69 6e 6e 69 6e 67  runs.  Beginning
2ebd0 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72   with SQLite ver
2ebe0 73 69 6f 6e 20 33 2e 35 2e 30 2c 20 74 68 65 20  sion 3.5.0, the 
2ebf0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
2ec00 69 73 0a 2a 2a 20 61 70 70 6c 69 65 64 20 74 6f  is.** applied to
2ec10 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 54 68   all threads. Th
2ec20 65 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  e value specifie
2ec30 64 20 66 6f 72 20 74 68 65 20 73 6f 66 74 20 68  d for the soft h
2ec40 65 61 70 20 6c 69 6d 69 74 0a 2a 2a 20 69 73 20  eap limit.** is 
2ec50 61 6e 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  an upper bound o
2ec60 6e 20 74 68 65 20 74 6f 74 61 6c 20 6d 65 6d 6f  n the total memo
2ec70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
2ec80 72 20 61 6c 6c 20 74 68 72 65 61 64 73 2e 20 49  r all threads. I
2ec90 6e 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 33 2e 35  n.** version 3.5
2eca0 2e 30 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d  .0 there is no m
2ecb0 65 63 68 61 6e 69 73 6d 20 66 6f 72 20 6c 69 6d  echanism for lim
2ecc0 69 74 69 6e 67 20 74 68 65 20 68 65 61 70 20 75  iting the heap u
2ecd0 73 61 67 65 20 66 6f 72 0a 2a 2a 20 69 6e 64 69  sage for.** indi
2ece0 76 69 64 75 61 6c 20 74 68 72 65 61 64 73 2e 0a  vidual threads..
2ecf0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
2ed00 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28  soft_heap_limit(
2ed10 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2ed20 49 33 52 45 46 3a 20 45 78 74 72 61 63 74 20 4d  I3REF: Extract M
2ed30 65 74 61 64 61 74 61 20 41 62 6f 75 74 20 41 20  etadata About A 
2ed40 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61 62 6c  Column Of A Tabl
2ed50 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  e.**.** ^This ro
2ed60 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 6d 65  utine returns me
2ed70 74 61 64 61 74 61 20 61 62 6f 75 74 20 61 20 73  tadata about a s
2ed80 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e 20 6f  pecific column o
2ed90 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  f a specific.** 
2eda0 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61  database table a
2edb0 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e 67 20  ccessible using 
2edc0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2edd0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
2ede0 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
2edf0 65 20 66 69 72 73 74 20 66 75 6e 63 74 69 6f 6e  e first function
2ee00 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2ee10 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20   ^The column is 
2ee20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
2ee30 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72 64 20  e second, third 
2ee40 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d  and fourth param
2ee50 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68 69 73  eters to.** this
2ee60 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68 65 20   function. ^The 
2ee70 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2ee80 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 6e   is either the n
2ee90 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2eea0 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22 6d 61  ase.** (i.e. "ma
2eeb0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f 72 20  in", "temp", or 
2eec0 61 6e 20 61 74 74 61 63 68 65 64 20 64 61 74 61  an attached data
2eed0 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69 6e 67  base) containing
2eee0 20 74 68 65 20 73 70 65 63 69 66 69 65 64 0a 2a   the specified.*
2eef0 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c 4c 2e  * table or NULL.
2ef00 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c 4c 2c   ^If it is NULL,
2ef10 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61 63 68   then all attach
2ef20 65 64 20 64 61 74 61 62 61 73 65 73 20 61 72 65  ed databases are
2ef30 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66 6f 72   searched.** for
2ef40 20 74 68 65 20 74 61 62 6c 65 20 75 73 69 6e 67   the table using
2ef50 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69   the same algori
2ef60 74 68 6d 20 75 73 65 64 20 62 79 20 74 68 65 20  thm used by the 
2ef70 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
2ef80 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20 75 6e  to.** resolve un
2ef90 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c 65 20  qualified table 
2efa0 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a 0a 2a  references..**.*
2efb0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64  * ^The third and
2efc0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2efd0 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  rs to this funct
2efe0 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61 62 6c  ion are the tabl
2eff0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  e and column.** 
2f000 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65 73 69  name of the desi
2f010 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65 73 70  red column, resp
2f020 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74 68 65  ectively. Neithe
2f030 72 20 6f 66 20 74 68 65 73 65 20 70 61 72 61 6d  r of these param
2f040 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62 65 20  eters.** may be 
2f050 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74  NULL..**.** ^Met
2f060 61 64 61 74 61 20 69 73 20 72 65 74 75 72 6e 65  adata is returne
2f070 64 20 62 79 20 77 72 69 74 69 6e 67 20 74 6f 20  d by writing to 
2f080 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63 61 74  the memory locat
2f090 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73 20 74  ions passed as t
2f0a0 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20 73 75  he 5th.** and su
2f0b0 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d 65 74  bsequent paramet
2f0c0 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63  ers to this func
2f0d0 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20 74 68  tion. ^Any of th
2f0e0 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20 6d 61  ese arguments ma
2f0f0 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20 69 6e  y be.** NULL, in
2f100 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
2f110 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 65 6c  corresponding el
2f120 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64 61 74  ement of metadat
2f130 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  a is omitted..**
2f140 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75 6f 74  .** ^(<blockquot
2f150 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2f160 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2f170 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72 20 3c  <th> Parameter <
2f180 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e 54 79  th> Output<br>Ty
2f190 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72 69 70  pe <th>  Descrip
2f1a0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  tion.**.** <tr><
2f1b0 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 5th <td> con
2f1c0 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 44 61  st char* <td> Da
2f1d0 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72 3e 3c  ta type.** <tr><
2f1e0 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63 6f 6e  td> 6th <td> con
2f1f0 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20 4e 61  st char* <td> Na
2f200 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20 63 6f  me of default co
2f210 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2f220 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37 74 68  .** <tr><td> 7th
2f230 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20   <td> int       
2f240 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63    <td> True if c
2f250 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f 54 20  olumn has a NOT 
2f260 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e 74 0a  NULL constraint.
2f270 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74 68 20  ** <tr><td> 8th 
2f280 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
2f290 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
2f2a0 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f 66 20  lumn is part of 
2f2b0 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45 59 0a  the PRIMARY KEY.
2f2c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74 68 20  ** <tr><td> 9th 
2f2d0 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20 20 20  <td> int        
2f2e0 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20 63 6f   <td> True if co
2f2f0 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49 4e 43  lumn is [AUTOINC
2f300 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74 61 62  REMENT].** </tab
2f310 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
2f320 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
2f330 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 64  e memory pointed
2f340 20 74 6f 20 62 79 20 74 68 65 20 63 68 61 72 61   to by the chara
2f350 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20 72 65  cter pointers re
2f360 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65 0a 2a  turned for the.*
2f370 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20 74 79  * declaration ty
2f380 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69 6f 6e  pe and collation
2f390 20 73 65 71 75 65 6e 63 65 20 69 73 20 76 61 6c   sequence is val
2f3a0 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20 74 68  id only until th
2f3b0 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c 20 74  e next.** call t
2f3c0 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41 50 49  o any SQLite API
2f3d0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
2f3e0 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
2f3f0 65 64 20 74 61 62 6c 65 20 69 73 20 61 63 74 75  ed table is actu
2f400 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61 6e 20  ally a view, an 
2f410 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
2f420 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2f430 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 65  ^If the specifie
2f440 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72 6f 77  d column is "row
2f450 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20 22 5f  id", "oid" or "_
2f460 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e 0a 2a  rowid_" and an.*
2f470 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  * [INTEGER PRIMA
2f480 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 20 68  RY KEY] column h
2f490 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63 69 74  as been explicit
2f4a0 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74 68 65  ly declared, the
2f4b0 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
2f4c0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
2f4d0 65 74 20 66 6f 72 20 74 68 65 20 65 78 70 6c 69  et for the expli
2f4e0 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63  citly declared c
2f4f0 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68 65 72  olumn. ^(If ther
2f500 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70 6c 69  e is no.** expli
2f510 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 5b  citly declared [
2f520 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
2f530 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74 68 65  KEY] column, the
2f540 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a 2a 20  n the output.** 
2f550 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 73  parameters are s
2f560 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  et as follows:.*
2f570 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20 20 20  *.** <pre>.**   
2f580 20 20 64 61 74 61 20 74 79 70 65 3a 20 22 49 4e    data type: "IN
2f590 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20 63 6f  TEGER".**     co
2f5a0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
2f5b0 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20 20 20  : "BINARY".**   
2f5c0 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a 2a 2a    not null: 0.**
2f5d0 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b 65 79       primary key
2f5e0 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74 6f 20  : 1.**     auto 
2f5f0 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a 2a 20  increment: 0.** 
2f600 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  </pre>)^.**.** ^
2f610 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d  (This function m
2f620 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72 20 6d  ay load one or m
2f630 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72 6f 6d  ore schemas from
2f640 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 2e   database files.
2f650 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20   If an.** error 
2f660 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
2f670 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  is process, or i
2f680 66 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  f the requested 
2f690 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 0a  table or column.
2f6a0 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66 6f 75  ** cannot be fou
2f6b0 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  nd, an [error co
2f6c0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  de] is returned 
2f6d0 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  and an error mes
2f6e0 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69 6e 20  sage left.** in 
2f6f0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2f700 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20 62 65  nnection] (to be
2f710 20 72 65 74 72 69 65 76 65 64 20 75 73 69 6e 67   retrieved using
2f720 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
2f730 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  )).)^.**.** ^Thi
2f740 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20 61 76  s API is only av
2f750 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2f760 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2f770 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2f780 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2f790 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2f7a0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2f7b0 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a  ymbol defined..*
2f7c0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 61  /.int sqlite3_ta
2f7d0 62 6c 65 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64  ble_column_metad
2f7e0 61 74 61 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ata(.  sqlite3 *
2f7f0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2f800 20 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e     /* Connection
2f810 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2f820 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65  st char *zDbName
2f830 2c 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61  ,        /* Data
2f840 62 61 73 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c  base name or NUL
2f850 4c 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  L */.  const cha
2f860 72 20 2a 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20  r *zTableName,  
2f870 20 20 20 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65     /* Table name
2f880 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2f890 20 2a 7a 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20   *zColumnName,  
2f8a0 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65    /* Column name
2f8b0 20 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74   */.  char const
2f8c0 20 2a 2a 70 7a 44 61 74 61 54 79 70 65 2c 20 20   **pzDataType,  
2f8d0 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 44 65 63    /* OUTPUT: Dec
2f8e0 6c 61 72 65 64 20 64 61 74 61 20 74 79 70 65 20  lared data type 
2f8f0 2a 2f 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20  */.  char const 
2f900 2a 2a 70 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20  **pzCollSeq,    
2f910 20 2f 2a 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c   /* OUTPUT: Coll
2f920 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e  ation sequence n
2f930 61 6d 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e  ame */.  int *pN
2f940 6f 74 4e 75 6c 6c 2c 20 20 20 20 20 20 20 20 20  otNull,         
2f950 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20       /* OUTPUT: 
2f960 54 72 75 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c  True if NOT NULL
2f970 20 63 6f 6e 73 74 72 61 69 6e 74 20 65 78 69 73   constraint exis
2f980 74 73 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72  ts */.  int *pPr
2f990 69 6d 61 72 79 4b 65 79 2c 20 20 20 20 20 20 20  imaryKey,       
2f9a0 20 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54      /* OUTPUT: T
2f9b0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61  rue if column pa
2f9c0 72 74 20 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e  rt of PK */.  in
2f9d0 74 20 2a 70 41 75 74 6f 69 6e 63 20 20 20 20 20  t *pAutoinc     
2f9e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
2f9f0 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
2fa00 75 6d 6e 20 69 73 20 61 75 74 6f 2d 69 6e 63 72  umn is auto-incr
2fa10 65 6d 65 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  ement */.);../*.
2fa20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61  ** CAPI3REF: Loa
2fa30 64 20 41 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a  d An Extension.*
2fa40 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
2fa50 66 61 63 65 20 6c 6f 61 64 73 20 61 6e 20 53 51  face loads an SQ
2fa60 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
2fa70 69 62 72 61 72 79 20 66 72 6f 6d 20 74 68 65 20  ibrary from the 
2fa80 6e 61 6d 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a  named file..**.*
2fa90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
2faa0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
2fab0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
2fac0 74 73 20 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a  ts to load an.**
2fad0 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
2fae0 6e 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  n library contai
2faf0 6e 65 64 20 69 6e 20 74 68 65 20 66 69 6c 65 20  ned in the file 
2fb00 7a 46 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  zFile..**.** ^Th
2fb10 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 69 73  e entry point is
2fb20 20 7a 50 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f   zProc..** ^zPro
2fb30 63 20 6d 61 79 20 62 65 20 30 2c 20 69 6e 20 77  c may be 0, in w
2fb40 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 61  hich case the na
2fb50 6d 65 20 6f 66 20 74 68 65 20 65 6e 74 72 79 20  me of the entry 
2fb60 70 6f 69 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74  point.** default
2fb70 73 20 74 6f 20 22 73 71 6c 69 74 65 33 5f 65 78  s to "sqlite3_ex
2fb80 74 65 6e 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a  tension_init"..*
2fb90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
2fba0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
2fbb0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2fbc0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  s.** [SQLITE_OK]
2fbd0 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
2fbe0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
2fbf0 66 20 73 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73  f something goes
2fc00 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61   wrong..** ^If a
2fc10 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 61  n error occurs a
2fc20 6e 64 20 70 7a 45 72 72 4d 73 67 20 69 73 20 6e  nd pzErrMsg is n
2fc30 6f 74 20 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a  ot 0, then the.*
2fc40 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  * [sqlite3_load_
2fc50 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74  extension()] int
2fc60 65 72 66 61 63 65 20 73 68 61 6c 6c 20 61 74 74  erface shall att
2fc70 65 6d 70 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20  empt to.** fill 
2fc80 2a 70 7a 45 72 72 4d 73 67 20 77 69 74 68 20 65  *pzErrMsg with e
2fc90 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
2fca0 74 20 73 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f  t stored in memo
2fcb0 72 79 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ry.** obtained f
2fcc0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
2fcd0 6c 6f 63 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c  loc()]. The call
2fce0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ing function.** 
2fcf0 73 68 6f 75 6c 64 20 66 72 65 65 20 74 68 69 73  should free this
2fd00 20 6d 65 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69   memory by calli
2fd10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
2fd20 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65  ()]..**.** ^Exte
2fd30 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75  nsion loading mu
2fd40 73 74 20 62 65 20 65 6e 61 62 6c 65 64 20 75 73  st be enabled us
2fd50 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2fd60 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
2fd70 6e 73 69 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74  nsion()] prior t
2fd80 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20 41  o calling this A
2fd90 50 49 2c 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  PI,.** otherwise
2fda0 20 61 6e 20 65 72 72 6f 72 20 77 69 6c 6c 20 62   an error will b
2fdb0 65 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  e returned..**.*
2fdc0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
2fdd0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
2fde0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
2fdf0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
2fe00 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a 20  oad_extension(. 
2fe10 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2fe20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20 74         /* Load t
2fe30 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e 74  he extension int
2fe40 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65 20  o this database 
2fe50 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20 20  connection */.  
2fe60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
2fe70 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66  e,    /* Name of
2fe80 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62 72   the shared libr
2fe90 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 65  ary containing e
2fea0 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63 6f  xtension */.  co
2feb0 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63 2c  nst char *zProc,
2fec0 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f 69      /* Entry poi
2fed0 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72 6f  nt.  Derived fro
2fee0 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f 0a  m zFile if 0 */.
2fef0 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73    char **pzErrMs
2ff00 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20 65  g       /* Put e
2ff10 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65 72  rror message her
2ff20 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29 3b  e if not 0 */.);
2ff30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ff40 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
2ff50 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f  ble Extension Lo
2ff60 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f 20  ading.**.** ^So 
2ff70 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20 73  as not to open s
2ff80 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69 6e  ecurity holes in
2ff90 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74 69   older applicati
2ffa0 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  ons that are.** 
2ffb0 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64 65  unprepared to de
2ffc0 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69 6f  al with extensio
2ffd0 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20 61  n loading, and a
2ffe0 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69 73  s a means of dis
2fff0 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e 73  abling.** extens
30000 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69 6c  ion loading whil
30010 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73 65  e evaluating use
30020 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20 74  r-entered SQL, t
30030 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50 49  he following API
30040 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64 20  .** is provided 
30050 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71 6c  to turn the [sql
30060 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
30070 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73 6d  ion()] mechanism
30080 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a 0a   on and off..**.
30090 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f  ** ^Extension lo
300a0 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79 20  ading is off by 
300b0 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69 63  default. See tic
300c0 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e 43  ket #1863..** ^C
300d0 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  all the sqlite3_
300e0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
300f0 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65 20  nsion() routine 
30100 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a 2a  with onoff==1.**
30110 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73 69   to turn extensi
30120 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61 6e  on loading on an
30130 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20 6f  d call it with o
30140 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e 0a  noff==0 to turn.
30150 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20 61  ** it back off a
30160 67 61 69 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gain..*/.int sql
30170 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64  ite3_enable_load
30180 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71 6c 69 74  _extension(sqlit
30190 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f 6e 6f 66  e3 *db, int onof
301a0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
301b0 52 45 46 3a 20 41 75 74 6f 6d 61 74 69 63 61 6c  REF: Automatical
301c0 6c 79 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  ly Load An Exten
301d0 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  sions.**.** ^Thi
301e0 73 20 41 50 49 20 63 61 6e 20 62 65 20 69 6e 76  s API can be inv
301f0 6f 6b 65 64 20 61 74 20 70 72 6f 67 72 61 6d 20  oked at program 
30200 73 74 61 72 74 75 70 20 69 6e 20 6f 72 64 65 72  startup in order
30210 20 74 6f 20 72 65 67 69 73 74 65 72 0a 2a 2a 20   to register.** 
30220 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 74 61 74  one or more stat
30230 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 65 78  ically linked ex
30240 74 65 6e 73 69 6f 6e 73 20 74 68 61 74 20 77 69  tensions that wi
30250 6c 6c 20 62 65 20 61 76 61 69 6c 61 62 6c 65 0a  ll be available.
30260 2a 2a 20 74 6f 20 61 6c 6c 20 6e 65 77 20 5b 64  ** to all new [d
30270 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30280 6f 6e 73 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ons]..**.** ^(Th
30290 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
302a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
302b0 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 65 6e 74  he extension ent
302c0 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 69 6e 20 61  ry point.** in a
302d0 6e 20 61 72 72 61 79 20 74 68 61 74 20 69 73 20  n array that is 
302e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
302f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
30300 2e 20 20 54 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  .  That memory.*
30310 2a 20 69 73 20 64 65 61 6c 6c 6f 63 61 74 65 64  * is deallocated
30320 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   by [sqlite3_res
30330 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
30340 6e 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  n()].)^.**.** ^T
30350 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  his function reg
30360 69 73 74 65 72 73 20 61 6e 20 65 78 74 65 6e 73  isters an extens
30370 69 6f 6e 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  ion entry point 
30380 74 68 61 74 20 69 73 0a 2a 2a 20 61 75 74 6f 6d  that is.** autom
30390 61 74 69 63 61 6c 6c 79 20 69 6e 76 6f 6b 65 64  atically invoked
303a0 20 77 68 65 6e 65 76 65 72 20 61 20 6e 65 77 20   whenever a new 
303b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
303c0 74 69 6f 6e 5d 0a 2a 2a 20 69 73 20 6f 70 65 6e  tion].** is open
303d0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
303e0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
303f0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a  te3_open16()],.*
30400 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
30410 65 6e 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 44 75  en_v2()]..** ^Du
30420 70 6c 69 63 61 74 65 20 65 78 74 65 6e 73 69 6f  plicate extensio
30430 6e 73 20 61 72 65 20 64 65 74 65 63 74 65 64 20  ns are detected 
30440 73 6f 20 63 61 6c 6c 69 6e 67 20 74 68 69 73 20  so calling this 
30450 72 6f 75 74 69 6e 65 0a 2a 2a 20 6d 75 6c 74 69  routine.** multi
30460 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 20 74  ple times with t
30470 68 65 20 73 61 6d 65 20 65 78 74 65 6e 73 69 6f  he same extensio
30480 6e 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 0a 2a  n is harmless..*
30490 2a 20 5e 41 75 74 6f 6d 61 74 69 63 20 65 78 74  * ^Automatic ext
304a0 65 6e 73 69 6f 6e 73 20 61 70 70 6c 79 20 61 63  ensions apply ac
304b0 72 6f 73 73 20 61 6c 6c 20 74 68 72 65 61 64 73  ross all threads
304c0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
304d0 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
304e0 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f 69  void (*xEntryPoi
304f0 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a 0a  nt)(void));../*.
30500 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
30510 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78 74  et Automatic Ext
30520 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a  ension Loading.*
30530 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63  *.** ^(This func
30540 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 61 6c  tion disables al
30550 6c 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 67  l previously reg
30560 69 73 74 65 72 65 64 20 61 75 74 6f 6d 61 74 69  istered automati
30570 63 0a 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 73 2e  c.** extensions.
30580 20 49 74 20 75 6e 64 6f 65 73 20 74 68 65 20 65   It undoes the e
30590 66 66 65 63 74 20 6f 66 20 61 6c 6c 20 70 72 69  ffect of all pri
305a0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  or.** [sqlite3_a
305b0 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  uto_extension()]
305c0 20 63 61 6c 6c 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20   calls.)^.**.** 
305d0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 64  ^This function d
305e0 69 73 61 62 6c 65 73 20 61 75 74 6f 6d 61 74 69  isables automati
305f0 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 6e 20  c extensions in 
30600 61 6c 6c 20 74 68 72 65 61 64 73 2e 0a 2a 2f 0a  all threads..*/.
30610 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
30620 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
30630 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  n(void);../*.** 
30640 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  The interface to
30650 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
30660 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69 73 20  le mechanism is 
30670 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73 69 64  currently consid
30680 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20 65 78  ered.** to be ex
30690 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54 68 65  perimental.  The
306a0 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67 68 74   interface might
306b0 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63 6f 6d   change in incom
306c0 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a 2a 2a  patible ways..**
306d0 20 49 66 20 74 68 69 73 20 69 73 20 61 20 70 72   If this is a pr
306e0 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c 20 64  oblem for you, d
306f0 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20 69 6e  o not use the in
30700 74 65 72 66 61 63 65 20 61 74 20 74 68 69 73 20  terface at this 
30710 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  time..**.** When
30720 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62   the virtual-tab
30730 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73 74 61  le mechanism sta
30740 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69 6c 6c  bilizes, we will
30750 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a 2a 20   declare the.** 
30760 69 6e 74 65 72 66 61 63 65 20 66 69 78 65 64 2c  interface fixed,
30770 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e 64 65   support it inde
30780 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20 72 65  finitely, and re
30790 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d 65 6e  move this commen
307a0 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 74 72  t..*/../*.** Str
307b0 75 63 74 75 72 65 73 20 75 73 65 64 20 62 79 20  uctures used by 
307c0 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
307d0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f 0a 74  e interface.*/.t
307e0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
307f0 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c 69 74  lite3_vtab sqlit
30800 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64 65 66  e3_vtab;.typedef
30810 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
30820 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c 69 74  index_info sqlit
30830 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b 0a 74  e3_index_info;.t
30840 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
30850 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
30860 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  r sqlite3_vtab_c
30870 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66 20 73  ursor;.typedef s
30880 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f  truct sqlite3_mo
30890 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d 6f 64  dule sqlite3_mod
308a0 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ule;../*.** CAPI
308b0 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
308c0 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ble Object.** KE
308d0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
308e0 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61 6c 20  module {virtual 
308f0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a 2a 2a  table module}.**
30900 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75  .** This structu
30910 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20 63 61  re, sometimes ca
30920 6c 6c 65 64 20 61 20 61 20 22 76 69 72 74 75 61  lled a a "virtua
30930 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c  l table module",
30940 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65   .** defines the
30950 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30960 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  of a [virtual ta
30970 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73  bles].  .** This
30980 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69   structure consi
30990 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65  sts mostly of me
309a0 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
309b0 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76  dule..**.** ^A v
309c0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
309d0 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62  ule is created b
309e0 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70  y filling in a p
309f0 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73  ersistent.** ins
30a00 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
30a10 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73  ructure and pass
30a20 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ing a pointer to
30a30 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a   that instance.*
30a40 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
30a50 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f  eate_module()] o
30a60 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
30a70 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a  e_module_v2()]..
30a80 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72 61  ** ^The registra
30a90 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c  tion remains val
30aa0 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72  id until it is r
30ab0 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 66  eplaced by a dif
30ac0 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65  ferent.** module
30ad0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64   or until the [d
30ae0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30af0 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65  on] closes.  The
30b00 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74   content.** of t
30b10 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d 75  his structure mu
30b20 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68  st not change wh
30b30 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 74  ile it is regist
30b40 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79  ered with.** any
30b50 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30b60 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  tion..*/.struct 
30b70 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
30b80 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
30b90 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65  .  int (*xCreate
30ba0 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
30bb0 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
30bc0 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
30bd0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
30be0 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
30bf0 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
30c00 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
30c10 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
30c20 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  xConnect)(sqlite
30c30 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
30c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
30c50 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
30c60 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
30c70 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
30c80 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
30c90 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
30ca0 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64    int (*xBestInd
30cb0 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ex)(sqlite3_vtab
30cc0 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33   *pVTab, sqlite3
30cd0 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20  _index_info*);. 
30ce0 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65   int (*xDisconne
30cf0 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ct)(sqlite3_vtab
30d00 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
30d10 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69  (*xDestroy)(sqli
30d20 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
30d30 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  ;.  int (*xOpen)
30d40 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
30d50 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74  VTab, sqlite3_vt
30d60 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75  ab_cursor **ppCu
30d70 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  rsor);.  int (*x
30d80 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
30d90 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
30da0 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73  int (*xFilter)(s
30db0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
30dc0 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c  or*, int idxNum,
30dd0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78   const char *idx
30de0 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Str,.           
30df0 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73       int argc, s
30e00 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61  qlite3_value **a
30e10 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e  rgv);.  int (*xN
30e20 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ext)(sqlite3_vta
30e30 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
30e40 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65  t (*xEof)(sqlite
30e50 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
30e60 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e  .  int (*xColumn
30e70 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
30e80 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
30e90 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
30ea0 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28    int (*xRowid)(
30eb0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
30ec0 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  sor*, sqlite3_in
30ed0 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20  t64 *pRowid);.  
30ee0 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73  int (*xUpdate)(s
30ef0 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69  qlite3_vtab *, i
30f00 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nt, sqlite3_valu
30f10 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  e **, sqlite3_in
30f20 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  t64 *);.  int (*
30f30 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f  xBegin)(sqlite3_
30f40 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
30f50 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
30f60 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
30f70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d  );.  int (*xComm
30f80 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  it)(sqlite3_vtab
30f90 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
30fa0 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c  (*xRollback)(sql
30fb0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
30fc0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64  );.  int (*xFind
30fd0 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65  Function)(sqlite
30fe0 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69  3_vtab *pVtab, i
30ff0 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63  nt nArg, const c
31000 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20  har *zName,.    
31010 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31020 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e     void (**pxFun
31030 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
31040 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31050 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20  value**),.      
31060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31070 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a   void **ppArg);.
31080 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29    int (*xRename)
31090 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
310a0 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72  Vtab, const char
310b0 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a   *zNew);.};../*.
310c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
310d0 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78  tual Table Index
310e0 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ing Information.
310f0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
31100 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a  ite3_index_info.
31110 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
31120 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
31130 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
31140 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
31150 75 73 65 64 20 74 6f 0a 2a 2a 20 70 61 73 73 20  used to.** pass 
31160 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 6e 74 6f  information into
31170 20 61 6e 64 20 72 65 63 65 69 76 65 20 74 68 65   and receive the
31180 20 72 65 70 6c 79 20 66 72 6f 6d 20 74 68 65 20   reply from the 
31190 5b 78 42 65 73 74 49 6e 64 65 78 5d 0a 2a 2a 20  [xBestIndex].** 
311a0 6d 65 74 68 6f 64 20 6f 66 20 61 20 5b 76 69 72  method of a [vir
311b0 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
311c0 65 5d 2e 20 20 54 68 65 20 66 69 65 6c 64 73 20  e].  The fields 
311d0 75 6e 64 65 72 20 2a 2a 49 6e 70 75 74 73 2a 2a  under **Inputs**
311e0 20 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 70 75   are the.** inpu
311f0 74 73 20 74 6f 20 78 42 65 73 74 49 6e 64 65 78  ts to xBestIndex
31200 20 61 6e 64 20 61 72 65 20 72 65 61 64 2d 6f 6e   and are read-on
31210 6c 79 2e 20 20 78 42 65 73 74 49 6e 64 65 78 20  ly.  xBestIndex 
31220 69 6e 73 65 72 74 73 20 69 74 73 0a 2a 2a 20 72  inserts its.** r
31230 65 73 75 6c 74 73 20 69 6e 74 6f 20 74 68 65 20  esults into the 
31240 2a 2a 4f 75 74 70 75 74 73 2a 2a 20 66 69 65 6c  **Outputs** fiel
31250 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ds..**.** ^(The 
31260 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
31270 72 61 79 20 72 65 63 6f 72 64 73 20 57 48 45 52  ray records WHER
31280 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
31290 69 6e 74 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ints of the form
312a0 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 63 6f 6c  :.**.** <pre>col
312b0 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f 70 72 65  umn OP expr</pre
312c0 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20 4f 50  >.**.** where OP
312d0 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26 6c 74   is =, &lt;, &lt
312e0 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26 67 74  ;=, &gt;, or &gt
312f0 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70 61 72  ;=.)^  ^(The par
31300 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74 6f 72  ticular operator
31310 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20 69 6e   is.** stored in
31320 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 6f   aConstraint[].o
31330 70 2e 29 5e 20 20 5e 28 54 68 65 20 69 6e 64 65  p.)^  ^(The inde
31340 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
31350 69 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20  is stored in.** 
31360 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43  aConstraint[].iC
31370 6f 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e  olumn.)^  ^(aCon
31380 73 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65  straint[].usable
31390 20 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a   is TRUE if the.
313a0 2a 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72  ** expr on the r
313b0 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63  ight-hand side c
313c0 61 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  an be evaluated 
313d0 28 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f  (and thus the co
313e0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75  nstraint.** is u
313f0 73 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65  sable) and false
31400 20 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e   if it cannot.)^
31410 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69  .**.** ^The opti
31420 6d 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61  mizer automatica
31430 6c 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d  lly inverts term
31440 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65  s of the form "e
31450 78 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a  xpr OP column".*
31460 2a 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65  * and makes othe
31470 72 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e  r simplification
31480 73 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63  s to the WHERE c
31490 6c 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65  lause in an atte
314a0 6d 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73  mpt to.** get as
314b0 20 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75   many WHERE clau
314c0 73 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68  se terms into th
314d0 65 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f  e form shown abo
314e0 76 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a  ve as possible..
314f0 2a 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61  ** ^The aConstra
31500 69 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79  int[] array only
31510 20 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63   reports WHERE c
31520 6c 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74  lause terms that
31530 20 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74   are.** relevant
31540 20 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c   to the particul
31550 61 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ar virtual table
31560 20 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a   being queried..
31570 2a 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69  **.** ^Informati
31580 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44  on about the ORD
31590 45 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20  ER BY clause is 
315a0 73 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72  stored in aOrder
315b0 42 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74  By[]..** ^Each t
315c0 65 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20  erm of aOrderBy 
315d0 72 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e  records a column
315e0 20 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59   of the ORDER BY
315f0 20 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54   clause..**.** T
31600 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20  he [xBestIndex] 
31610 6d 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c  method must fill
31620 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67   aConstraintUsag
31630 65 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61  e[] with informa
31640 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68  tion.** about wh
31650 61 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  at parameters to
31660 20 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72   pass to xFilter
31670 2e 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78  .  ^If argvIndex
31680 3e 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72  >0 then.** the r
31690 69 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  ight-hand side o
316a0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
316b0 69 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  ing aConstraint[
316c0 5d 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a  ] is evaluated.*
316d0 2a 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68  * and becomes th
316e0 65 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65  e argvIndex-th e
316f0 6e 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e  ntry in argv.  ^
31700 28 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55  (If aConstraintU
31710 73 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69  sage[].omit.** i
31720 73 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65  s true, then the
31730 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61   constraint is a
31740 73 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c  ssumed to be ful
31750 6c 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68  ly handled by th
31760 65 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62  e.** virtual tab
31770 6c 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68  le and is not ch
31780 65 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53  ecked again by S
31790 51 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  QLite.)^.**.** ^
317a0 54 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69  The idxNum and i
317b0 64 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65  dxPtr values are
317c0 20 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61   recorded and pa
317d0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ssed into the.**
317e0 20 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f   [xFilter] metho
317f0 64 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f  d..** ^[sqlite3_
31800 66 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20  free()] is used 
31810 74 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69  to free idxPtr i
31820 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
31830 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74   needToFreeIdxPt
31840 72 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a  r is true..**.**
31850 20 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e   ^The orderByCon
31860 73 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74  sumed means that
31870 20 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46   output from [xF
31880 69 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77  ilter]/[xNext] w
31890 69 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20  ill occur in.** 
318a0 74 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65  the correct orde
318b0 72 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65  r to satisfy the
318c0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
318d0 20 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61   so that no sepa
318e0 72 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20  rate.** sorting 
318f0 73 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64  step is required
31900 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74  ..**.** ^The est
31910 69 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65  imatedCost value
31920 20 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20   is an estimate 
31930 6f 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64  of the cost of d
31940 6f 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74  oing the.** part
31950 69 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20  icular lookup.  
31960 41 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61  A full scan of a
31970 20 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e   table with N en
31980 74 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76  tries should hav
31990 65 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e  e.** a cost of N
319a0 2e 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72  .  A binary sear
319b0 63 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66  ch of a table of
319c0 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c   N entries shoul
319d0 64 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74  d have a.** cost
319e0 20 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c   of approximatel
319f0 79 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72  y log(N)..*/.str
31a00 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
31a10 78 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e  x_info {.  /* In
31a20 70 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43  puts */.  int nC
31a30 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20  onstraint;      
31a40 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
31a50 66 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f  f entries in aCo
31a60 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74  nstraint */.  st
31a70 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64  ruct sqlite3_ind
31a80 65 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a  ex_constraint {.
31a90 20 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e       int iColumn
31aa0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
31ab0 2a 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74  * Column on left
31ac0 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f  -hand side of co
31ad0 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20  nstraint */.    
31ae0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
31af0 70 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f  p;         /* Co
31b00 6e 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f  nstraint operato
31b10 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  r */.     unsign
31b20 65 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20  ed char usable; 
31b30 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74      /* True if t
31b40 68 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  his constraint i
31b50 73 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20  s usable */.    
31b60 20 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74   int iTermOffset
31b70 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73  ;          /* Us
31b80 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20  ed internally - 
31b90 78 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c  xBestIndex shoul
31ba0 64 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20  d ignore */.  } 
31bb0 2a 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20  *aConstraint;   
31bc0 20 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c           /* Tabl
31bd0 65 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73  e of WHERE claus
31be0 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f  e constraints */
31bf0 0a 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b  .  int nOrderBy;
31c00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
31c10 20 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   Number of terms
31c20 20 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59   in the ORDER BY
31c30 20 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72   clause */.  str
31c40 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
31c50 78 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20  x_orderby {.    
31c60 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20   int iColumn;   
31c70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
31c80 6c 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20  lumn number */. 
31c90 20 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61      unsigned cha
31ca0 72 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a  r desc;       /*
31cb0 20 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20   True for DESC. 
31cc0 20 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20   False for ASC. 
31cd0 2a 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79  */.  } *aOrderBy
31ce0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
31cf0 2f 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20  /* The ORDER BY 
31d00 63 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f  clause */.  /* O
31d10 75 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75  utputs */.  stru
31d20 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
31d30 5f 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67  _constraint_usag
31d40 65 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76  e {.    int argv
31d50 49 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20  Index;          
31d60 20 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74   /* if >0, const
31d70 72 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66  raint is part of
31d80 20 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72   argv to xFilter
31d90 20 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64   */.    unsigned
31da0 20 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20   char omit;     
31db0 20 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20   /* Do not code 
31dc0 61 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20  a test for this 
31dd0 63 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20  constraint */.  
31de0 7d 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  } *aConstraintUs
31df0 61 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75  age;.  int idxNu
31e00 6d 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  m;              
31e10 20 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64    /* Number used
31e20 20 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65   to identify the
31e30 20 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72   index */.  char
31e40 20 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20   *idxStr;       
31e50 20 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67         /* String
31e60 2c 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69  , possibly obtai
31e70 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
31e80 5f 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74  _malloc */.  int
31e90 20 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74   needToFreeIdxSt
31ea0 72 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20  r;      /* Free 
31eb0 69 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c  idxStr using sql
31ec0 69 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74  ite3_free() if t
31ed0 72 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64  rue */.  int ord
31ee0 65 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20  erByConsumed;   
31ef0 20 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f      /* True if o
31f00 75 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79  utput is already
31f10 20 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f   ordered */.  do
31f20 75 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f  uble estimatedCo
31f30 73 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69  st;      /* Esti
31f40 6d 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73  mated cost of us
31f50 69 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a  ing this index *
31f60 2f 0a 7d 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c  /.};.#define SQL
31f70 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
31f80 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65  AINT_EQ    2.#de
31f90 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
31fa0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20  X_CONSTRAINT_GT 
31fb0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
31fc0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
31fd0 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65  AINT_LE    8.#de
31fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
31ff0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20  X_CONSTRAINT_LT 
32000 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
32010 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
32020 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23  RAINT_GE    32.#
32030 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
32040 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d  DEX_CONSTRAINT_M
32050 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43  ATCH 64../*.** C
32060 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
32070 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  r A Virtual Tabl
32080 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e Implementation
32090 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
320a0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
320b0 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65  to register a ne
320c0 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  w [virtual table
320d0 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a   module] name..*
320e0 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20  * ^Module names 
320f0 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72  must be register
32100 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65  ed before.** cre
32110 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72  ating a new [vir
32120 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e  tual table] usin
32130 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64  g the module and
32140 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a   before using a.
32150 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b  ** preexisting [
32160 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66  virtual table] f
32170 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a  or the module..*
32180 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65  *.** ^The module
32190 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74 65   name is registe
321a0 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  red on the [data
321b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
321c0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
321d0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
321e0 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65  eter.  ^The name
321f0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
32200 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a  s given by the .
32210 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
32220 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64  ter.  ^The third
32230 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
32240 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68  pointer to.** th
32250 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32260 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
32270 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
32280 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a    ^The fourth.**
32290 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
322a0 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e   arbitrary clien
322b0 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  t data pointer t
322c0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68  hat is passed th
322d0 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68  rough.** into th
322e0 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20  e [xCreate] and 
322f0 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f  [xConnect] metho
32300 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61  ds of the virtua
32310 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a  l table module.*
32320 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72  * when a new vir
32330 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65  tual table is be
32340 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f   being created o
32350 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e  r reinitialized.
32360 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32370 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
32380 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
32390 20 68 61 73 20 61 20 66 69 66 74 68 20 70 61 72   has a fifth par
323a0 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
323b0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
323c0 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  a destructor for
323d0 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61   the pClientData
323e0 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a  .  ^SQLite will.
323f0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ** invoke the de
32400 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
32410 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20  n (if it is not 
32420 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74  NULL) when SQLit
32430 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e  e.** no longer n
32440 65 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74  eeds the pClient
32450 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e  Data pointer.  ^
32460 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
32470 74 65 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69  te_module().** i
32480 6e 74 65 72 66 61 63 65 20 69 73 20 65 71 75 69  nterface is equi
32490 76 61 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  valent to sqlite
324a0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f  3_create_module_
324b0 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
324c0 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 2e 0a  .** destructor..
324d0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
324e0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20  reate_module(.  
324f0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
32500 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
32510 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
32520 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
32530 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
32540 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
32550 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
32560 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
32570 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
32580 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a  _module *p,   /*
32590 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
325a0 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
325b0 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20  d *pClientData  
325c0 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
325d0 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
325e0 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29  te/xConnect */.)
325f0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
32600 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a  eate_module_v2(.
32610 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
32620 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
32630 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f  SQLite connectio
32640 6e 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f  n to register mo
32650 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63  dule with */.  c
32660 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
32670 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  ,         /* Nam
32680 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
32690 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74  */.  const sqlit
326a0 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20  e3_module *p,   
326b0 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74  /* Methods for t
326c0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76  he module */.  v
326d0 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61  oid *pClientData
326e0 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69  ,         /* Cli
326f0 65 6e 74 20 64 61 74 61 20 66 6f 72 20 78 43 72  ent data for xCr
32700 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f  eate/xConnect */
32710 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
32720 79 29 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a  y)(void*)     /*
32730 20 4d 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74   Module destruct
32740 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29  or function */.)
32750 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32760 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65  F: Virtual Table
32770 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74   Instance Object
32780 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
32790 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a  lite3_vtab.**.**
327a0 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20   Every [virtual 
327b0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d  table module] im
327c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
327d0 73 20 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20  s a subclass.** 
327e0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74  of this object t
327f0 6f 20 64 65 73 63 72 69 62 65 20 61 20 70 61 72  o describe a par
32800 74 69 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65  ticular instance
32810 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74  .** of the [virt
32820 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63  ual table].  Eac
32830 68 20 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a  h subclass will.
32840 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74  ** be tailored t
32850 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
32860 65 65 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75  eeds of the modu
32870 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
32880 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73  n..** The purpos
32890 65 20 6f 66 20 74 68 69 73 20 73 75 70 65 72 63  e of this superc
328a0 6c 61 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e  lass is to defin
328b0 65 20 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73  e certain fields
328c0 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d   that are.** com
328d0 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c  mon to all modul
328e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
328f0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61  s..**.** ^Virtua
32900 6c 20 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73  l tables methods
32910 20 63 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f   can set an erro
32920 72 20 6d 65 73 73 61 67 65 20 62 79 20 61 73 73  r message by ass
32930 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69  igning a.** stri
32940 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
32950 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
32960 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e  f()] to zErrMsg.
32970 20 20 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f    The method sho
32980 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65  uld.** take care
32990 20 74 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20   that any prior 
329a0 73 74 72 69 6e 67 20 69 73 20 66 72 65 65 64 20  string is freed 
329b0 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  by a call to [sq
329c0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a  lite3_free()].**
329d0 20 70 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e   prior to assign
329e0 69 6e 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67  ing a new string
329f0 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41   to zErrMsg.  ^A
32a00 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d  fter the error m
32a10 65 73 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c  essage.** is del
32a20 69 76 65 72 65 64 20 75 70 20 74 6f 20 74 68 65  ivered up to the
32a30 20 63 6c 69 65 6e 74 20 61 70 70 6c 69 63 61 74   client applicat
32a40 69 6f 6e 2c 20 74 68 65 20 73 74 72 69 6e 67 20  ion, the string 
32a50 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
32a60 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62  cally.** freed b
32a70 79 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  y sqlite3_free()
32a80 20 61 6e 64 20 74 68 65 20 7a 45 72 72 4d 73 67   and the zErrMsg
32a90 20 66 69 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a   field will be z
32aa0 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74  eroed..*/.struct
32ab0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a   sqlite3_vtab {.
32ac0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
32ad0 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b  module *pModule;
32ae0 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20    /* The module 
32af0 66 6f 72 20 74 68 69 73 20 76 69 72 74 75 61 6c  for this virtual
32b00 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20   table */.  int 
32b10 6e 52 65 66 3b 20 20 20 20 20 20 20 20 20 20 20  nRef;           
32b20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e              /* N
32b30 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f  O LONGER USED */
32b40 0a 20 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  .  char *zErrMsg
32b50 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
32b60 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73     /* Error mess
32b70 61 67 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  age from sqlite3
32b80 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20  _mprintf() */.  
32b90 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
32ba0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
32bb0 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20   will typically 
32bc0 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  add additional f
32bd0 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  ields */.};../*.
32be0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
32bf0 74 75 61 6c 20 54 61 62 6c 65 20 43 75 72 73 6f  tual Table Curso
32c00 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  r Object.** KEYW
32c10 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 74  ORDS: sqlite3_vt
32c20 61 62 5f 63 75 72 73 6f 72 20 7b 76 69 72 74 75  ab_cursor {virtu
32c30 61 6c 20 74 61 62 6c 65 20 63 75 72 73 6f 72 7d  al table cursor}
32c40 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69  .**.** Every [vi
32c50 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
32c60 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  le] implementati
32c70 6f 6e 20 75 73 65 73 20 61 20 73 75 62 63 6c 61  on uses a subcla
32c80 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c  ss of the.** fol
32c90 6c 6f 77 69 6e 67 20 73 74 72 75 63 74 75 72 65  lowing structure
32ca0 20 74 6f 20 64 65 73 63 72 69 62 65 20 63 75 72   to describe cur
32cb0 73 6f 72 73 20 74 68 61 74 20 70 6f 69 6e 74 20  sors that point 
32cc0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72  into the.** [vir
32cd0 74 75 61 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20  tual table] and 
32ce0 61 72 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c  are used.** to l
32cf0 6f 6f 70 20 74 68 72 6f 75 67 68 20 74 68 65 20  oop through the 
32d00 76 69 72 74 75 61 6c 20 74 61 62 6c 65 2e 20 20  virtual table.  
32d10 43 75 72 73 6f 72 73 20 61 72 65 20 63 72 65 61  Cursors are crea
32d20 74 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ted using the.**
32d30 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65   [sqlite3_module
32d40 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20  .xOpen | xOpen] 
32d50 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f  method of the mo
32d60 64 75 6c 65 20 61 6e 64 20 61 72 65 20 64 65 73  dule and are des
32d70 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20 74 68 65  troyed.** by the
32d80 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65   [sqlite3_module
32d90 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65  .xClose | xClose
32da0 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75 72 73 6f  ] method.  Curso
32db0 72 73 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 62  rs are used.** b
32dc0 79 20 74 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c  y the [xFilter],
32dd0 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d   [xNext], [xEof]
32de0 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64  , [xColumn], and
32df0 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64   [xRowid] method
32e00 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75  s.** of the modu
32e10 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64 75 6c 65  le.  Each module
32e20 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32e30 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74  will define.** t
32e40 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20  he content of a 
32e50 63 75 72 73 6f 72 20 73 74 72 75 63 74 75 72 65  cursor structure
32e60 20 74 6f 20 73 75 69 74 20 69 74 73 20 6f 77 6e   to suit its own
32e70 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
32e80 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 65 78  is superclass ex
32e90 69 73 74 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  ists in order to
32ea0 20 64 65 66 69 6e 65 20 66 69 65 6c 64 73 20 6f   define fields o
32eb0 66 20 74 68 65 20 63 75 72 73 6f 72 20 74 68 61  f the cursor tha
32ec0 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20  t.** are common 
32ed0 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  to all implement
32ee0 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63  ations..*/.struc
32ef0 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  t sqlite3_vtab_c
32f00 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65  ursor {.  sqlite
32f10 33 5f 76 74 61 62 20 2a 70 56 74 61 62 3b 20 20  3_vtab *pVtab;  
32f20 20 20 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74      /* Virtual t
32f30 61 62 6c 65 20 6f 66 20 74 68 69 73 20 63 75 72  able of this cur
32f40 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74  sor */.  /* Virt
32f50 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d  ual table implem
32f60 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74  entations will t
32f70 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64 64  ypically add add
32f80 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a  itional fields *
32f90 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
32fa0 33 52 45 46 3a 20 44 65 63 6c 61 72 65 20 54 68  3REF: Declare Th
32fb0 65 20 53 63 68 65 6d 61 20 4f 66 20 41 20 56 69  e Schema Of A Vi
32fc0 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a  rtual Table.**.*
32fd0 2a 20 5e 54 68 65 20 5b 78 43 72 65 61 74 65 5d  * ^The [xCreate]
32fe0 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20   and [xConnect] 
32ff0 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20  methods of a.** 
33000 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
33010 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73  odule] call this
33020 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f   interface.** to
33030 20 64 65 63 6c 61 72 65 20 74 68 65 20 66 6f 72   declare the for
33040 6d 61 74 20 28 74 68 65 20 6e 61 6d 65 73 20 61  mat (the names a
33050 6e 64 20 64 61 74 61 74 79 70 65 73 20 6f 66 20  nd datatypes of 
33060 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a  the columns) of.
33070 2a 2a 20 74 68 65 20 76 69 72 74 75 61 6c 20 74  ** the virtual t
33080 61 62 6c 65 73 20 74 68 65 79 20 69 6d 70 6c 65  ables they imple
33090 6d 65 6e 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ment..*/.int sql
330a0 69 74 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61  ite3_declare_vta
330b0 62 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73  b(sqlite3*, cons
330c0 74 20 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a  t char *zSQL);..
330d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
330e0 4f 76 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74  Overload A Funct
330f0 69 6f 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61  ion For A Virtua
33100 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28  l Table.**.** ^(
33110 56 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63  Virtual tables c
33120 61 6e 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72  an provide alter
33130 6e 61 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74  native implement
33140 61 74 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69  ations of functi
33150 6f 6e 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  ons.** using the
33160 20 5b 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d   [xFindFunction]
33170 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
33180 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
33190 64 75 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20  dule].  .** But 
331a0 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20  global versions 
331b0 6f 66 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f  of those functio
331c0 6e 73 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74  ns.** must exist
331d0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20   in order to be 
331e0 6f 76 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a  overloaded.)^.**
331f0 0a 2a 2a 20 5e 28 54 68 69 73 20 41 50 49 20 6d  .** ^(This API m
33200 61 6b 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62  akes sure a glob
33210 61 6c 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20  al version of a 
33220 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
33230 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61  particular.** na
33240 6d 65 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66  me and number of
33250 20 70 61 72 61 6d 65 74 65 72 73 20 65 78 69 73   parameters exis
33260 74 73 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20  ts.  If no such 
33270 66 75 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a  function exists.
33280 2a 2a 20 62 65 66 6f 72 65 20 74 68 69 73 20 41  ** before this A
33290 50 49 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20  PI is called, a 
332a0 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
332b0 63 72 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 65  created.)^  ^The
332c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
332d0 2a 2a 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75  ** of the new fu
332e0 6e 63 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61  nction always ca
332f0 75 73 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f  uses an exceptio
33300 6e 20 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20  n to be thrown. 
33310 20 53 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66   So.** the new f
33320 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67  unction is not g
33330 6f 6f 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67  ood for anything
33340 20 62 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73   by itself.  Its
33350 20 6f 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65   only.** purpose
33360 20 69 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63   is to be a plac
33370 65 68 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e  eholder function
33380 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
33390 72 6c 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20  rloaded.** by a 
333a0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e  [virtual table].
333b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
333c0 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f  overload_functio
333d0 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73  n(sqlite3*, cons
333e0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d  t char *zFuncNam
333f0 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f  e, int nArg);../
33400 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61  *.** The interfa
33410 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61  ce to the virtua
33420 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
33430 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20  m defined above 
33440 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61  (back up.** to a
33450 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61   comment remarka
33460 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74  bly similar to t
33470 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72  his one) is curr
33480 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
33490 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
334a0 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
334b0 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
334c0 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
334d0 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
334e0 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
334f0 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
33500 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
33510 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
33520 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
33530 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
33540 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
33550 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
33560 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
33570 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
33580 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
33590 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
335a0 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
335b0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
335c0 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41  F: A Handle To A
335d0 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b  n Open BLOB.** K
335e0 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68  EYWORDS: {BLOB h
335f0 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e  andle} {BLOB han
33600 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  dles}.**.** An i
33610 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
33620 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
33630 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f  s an open BLOB o
33640 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  n which.** [sqli
33650 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
33660 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
33670 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72   I/O] can be per
33680 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65  formed..** ^Obje
33690 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65  cts of this type
336a0 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20   are created by 
336b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
336c0 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73  en()].** and des
336d0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
336e0 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
336f0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
33700 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
33710 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
33720 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72  b_write()] inter
33730 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20  faces.** can be 
33740 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20  used to read or 
33750 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73  write small subs
33760 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42  ections of the B
33770 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  LOB..** ^The [sq
33780 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
33790 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
337a0 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
337b0 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79  f the BLOB in by
337c0 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  tes..*/.typedef 
337d0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62  struct sqlite3_b
337e0 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  lob sqlite3_blob
337f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33800 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46  F: Open A BLOB F
33810 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49  or Incremental I
33820 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  /O.**.** ^(This 
33830 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73  interfaces opens
33840 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20   a [BLOB handle 
33850 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65  | handle] to the
33860 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a   BLOB located.**
33870 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f   in row iRow, co
33880 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61  lumn zColumn, ta
33890 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
338a0 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69  tabase zDb;.** i
338b0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
338c0 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61  he same BLOB tha
338d0 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63  t would be selec
338e0 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ted by:.**.** <p
338f0 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43  re>.**     SELEC
33900 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a  T zColumn FROM z
33910 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20  Db.zTable WHERE 
33920 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a  [rowid] = iRow;.
33930 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a  ** </pre>)^.**.*
33940 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20  * ^If the flags 
33950 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
33960 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
33970 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
33980 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77  or read.** and w
33990 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66  rite access. ^If
339a0 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65   it is zero, the
339b0 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20   BLOB is opened 
339c0 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e  for read access.
339d0 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70  .** ^It is not p
339e0 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20  ossible to open 
339f0 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  a column that is
33a00 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65   part of an inde
33a10 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a  x or primary .**
33a20 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67   key for writing
33a30 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b  . ^If [foreign k
33a40 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20  ey constraints] 
33a50 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20  are enabled, it 
33a60 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69  is .** not possi
33a70 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f  ble to open a co
33a80 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72  lumn that is par
33a90 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65  t of a [child ke
33aa0 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a  y] for writing..
33ab0 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
33ac0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
33ad0 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69  me is not the fi
33ae0 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74  lename that cont
33af0 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61  ains.** the data
33b00 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20  base but rather 
33b10 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  the symbolic nam
33b20 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
33b30 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72  e that.** appear
33b40 73 20 61 66 74 65 72 20 74 68 65 20 41 53 20 6b  s after the AS k
33b50 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20  eyword when the 
33b60 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e  database is conn
33b70 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54  ected using [ATT
33b80 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68  ACH]..** ^For th
33b90 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
33ba0 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61  file, the databa
33bb0 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e  se name is "main
33bc0 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20  "..** ^For TEMP 
33bd0 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61  tables, the data
33be0 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65  base name is "te
33bf0 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20  mp"..**.** ^(On 
33c00 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45  success, [SQLITE
33c10 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
33c20 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c   and the new [BL
33c30 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72  OB handle] is wr
33c40 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42  itten.** to *ppB
33c50 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61  lob. Otherwise a
33c60 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
33c70 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a  s returned and *
33c80 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a  ppBlob is set.**
33c90 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f   to be a null po
33ca0 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69  inter.)^.** ^Thi
33cb0 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20  s function sets 
33cc0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
33cd0 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20  nnection] error 
33ce0 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
33cf0 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76  .** accessible v
33d00 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
33d10 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ode()] and [sqli
33d20 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e  te3_errmsg()] an
33d30 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e  d related.** fun
33d40 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68  ctions. ^Note th
33d50 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76  at the *ppBlob v
33d60 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79  ariable is alway
33d70 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e  s initialized in
33d80 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d   a.** way that m
33d90 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20  akes it safe to 
33da0 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
33db0 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e  blob_close()] on
33dc0 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61   *ppBlob.** rega
33dd0 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75  rdless of the su
33de0 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
33df0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
33e00 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65  ..**.** ^(If the
33e10 20 72 6f 77 20 74 68 61 74 20 61 20 42 4c 4f 42   row that a BLOB
33e20 20 68 61 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74   handle points t
33e30 6f 20 69 73 20 6d 6f 64 69 66 69 65 64 20 62 79  o is modified by
33e40 20 61 6e 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c   an.** [UPDATE],
33e50 20 5b 44 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79   [DELETE], or by
33e60 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73   [ON CONFLICT] s
33e70 69 64 65 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74  ide-effects.** t
33e80 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 68 61 6e  hen the BLOB han
33e90 64 6c 65 20 69 73 20 6d 61 72 6b 65 64 20 61 73  dle is marked as
33ea0 20 22 65 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54   "expired"..** T
33eb0 68 69 73 20 69 73 20 74 72 75 65 20 69 66 20 61  his is true if a
33ec0 6e 79 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  ny column of the
33ed0 20 72 6f 77 20 69 73 20 63 68 61 6e 67 65 64 2c   row is changed,
33ee0 20 65 76 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a   even a column.*
33ef0 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 74 68 65  * other than the
33f00 20 6f 6e 65 20 74 68 65 20 42 4c 4f 42 20 68 61   one the BLOB ha
33f10 6e 64 6c 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e  ndle is open on.
33f20 29 5e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  )^.** ^Calls to 
33f30 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65  [sqlite3_blob_re
33f40 61 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ad()] and [sqlit
33f50 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d  e3_blob_write()]
33f60 20 66 6f 72 0a 2a 2a 20 61 20 65 78 70 69 72 65   for.** a expire
33f70 64 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61  d BLOB handle fa
33f80 69 6c 20 77 69 74 68 20 61 6e 20 72 65 74 75 72  il with an retur
33f90 6e 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54  n code of [SQLIT
33fa0 45 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43  E_ABORT]..** ^(C
33fb0 68 61 6e 67 65 73 20 77 72 69 74 74 65 6e 20 69  hanges written i
33fc0 6e 74 6f 20 61 20 42 4c 4f 42 20 70 72 69 6f 72  nto a BLOB prior
33fd0 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 65 78 70   to the BLOB exp
33fe0 69 72 69 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a  iring are not.**
33ff0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79 20   rolled back by 
34000 74 68 65 20 65 78 70 69 72 61 74 69 6f 6e 20 6f  the expiration o
34010 66 20 74 68 65 20 42 4c 4f 42 2e 20 20 53 75 63  f the BLOB.  Suc
34020 68 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 65  h changes will e
34030 76 65 6e 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d  ventually.** com
34040 6d 69 74 20 69 66 20 74 68 65 20 74 72 61 6e 73  mit if the trans
34050 61 63 74 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73  action continues
34060 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29   to completion.)
34070 5e 0a 2a 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65  ^.**.** ^Use the
34080 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62   [sqlite3_blob_b
34090 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  ytes()] interfac
340a0 65 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74  e to determine t
340b0 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68  he size of.** th
340c0 65 20 6f 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20  e opened blob.  
340d0 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 61 20 62  ^The size of a b
340e0 6c 6f 62 20 6d 61 79 20 6e 6f 74 20 62 65 20 63  lob may not be c
340f0 68 61 6e 67 65 64 20 62 79 20 74 68 69 73 0a 2a  hanged by this.*
34100 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 55 73  * interface.  Us
34110 65 20 74 68 65 20 5b 55 50 44 41 54 45 5d 20 53  e the [UPDATE] S
34120 51 4c 20 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68  QL command to ch
34130 61 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66  ange the size of
34140 20 61 0a 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a   a.** blob..**.*
34150 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
34160 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d  bind_zeroblob()]
34170 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
34180 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d  sult_zeroblob()]
34190 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
341a0 6e 64 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  nd the built-in 
341b0 5b 7a 65 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66  [zeroblob] SQL f
341c0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 75  unction can be u
341d0 73 65 64 2c 20 69 66 20 64 65 73 69 72 65 64 2c  sed, if desired,
341e0 0a 2a 2a 20 74 6f 20 63 72 65 61 74 65 20 61 6e  .** to create an
341f0 20 65 6d 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c   empty, zero-fil
34200 6c 65 64 20 62 6c 6f 62 20 69 6e 20 77 68 69 63  led blob in whic
34210 68 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69  h to read or wri
34220 74 65 20 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73  te using.** this
34230 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
34240 2a 20 54 6f 20 61 76 6f 69 64 20 61 20 72 65 73  * To avoid a res
34250 6f 75 72 63 65 20 6c 65 61 6b 2c 20 65 76 65 72  ource leak, ever
34260 79 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e  y open [BLOB han
34270 64 6c 65 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e  dle] should even
34280 74 75 61 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c  tually.** be rel
34290 65 61 73 65 64 20 62 79 20 61 20 63 61 6c 6c 20  eased by a call 
342a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  to [sqlite3_blob
342b0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e  _close()]..*/.in
342c0 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f  t sqlite3_blob_o
342d0 70 65 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  pen(.  sqlite3*,
342e0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
342f0 44 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  Db,.  const char
34300 20 2a 7a 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73   *zTable,.  cons
34310 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c  t char *zColumn,
34320 0a 20 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  .  sqlite3_int64
34330 20 69 52 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61   iRow,.  int fla
34340 67 73 2c 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c  gs,.  sqlite3_bl
34350 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a  ob **ppBlob.);..
34360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34370 43 6c 6f 73 65 20 41 20 42 4c 4f 42 20 48 61 6e  Close A BLOB Han
34380 64 6c 65 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 65  dle.**.** ^Close
34390 73 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f 42 20  s an open [BLOB 
343a0 68 61 6e 64 6c 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  handle]..**.** ^
343b0 43 6c 6f 73 69 6e 67 20 61 20 42 4c 4f 42 20 73  Closing a BLOB s
343c0 68 61 6c 6c 20 63 61 75 73 65 20 74 68 65 20 63  hall cause the c
343d0 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
343e0 6f 6e 20 74 6f 20 63 6f 6d 6d 69 74 0a 2a 2a 20  on to commit.** 
343f0 69 66 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  if there are no 
34400 6f 74 68 65 72 20 42 4c 4f 42 73 2c 20 6e 6f 20  other BLOBs, no 
34410 70 65 6e 64 69 6e 67 20 70 72 65 70 61 72 65 64  pending prepared
34420 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 61 6e 64   statements, and
34430 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
34440 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 69   connection is i
34450 6e 20 5b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  n [autocommit mo
34460 64 65 5d 2e 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  de]..** ^If any 
34470 77 72 69 74 65 73 20 77 65 72 65 20 6d 61 64 65  writes were made
34480 20 74 6f 20 74 68 65 20 42 4c 4f 42 2c 20 74 68   to the BLOB, th
34490 65 79 20 6d 69 67 68 74 20 62 65 20 68 65 6c 64  ey might be held
344a0 20 69 6e 20 63 61 63 68 65 0a 2a 2a 20 75 6e 74   in cache.** unt
344b0 69 6c 20 74 68 65 20 63 6c 6f 73 65 20 6f 70 65  il the close ope
344c0 72 61 74 69 6f 6e 20 69 66 20 74 68 65 79 20 77  ration if they w
344d0 69 6c 6c 20 66 69 74 2e 0a 2a 2a 0a 2a 2a 20 5e  ill fit..**.** ^
344e0 28 43 6c 6f 73 69 6e 67 20 74 68 65 20 42 4c 4f  (Closing the BLO
344f0 42 20 6f 66 74 65 6e 20 66 6f 72 63 65 73 20 74  B often forces t
34500 68 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 75  he changes.** ou
34510 74 20 74 6f 20 64 69 73 6b 20 61 6e 64 20 73 6f  t to disk and so
34520 20 69 66 20 61 6e 79 20 49 2f 4f 20 65 72 72 6f   if any I/O erro
34530 72 73 20 6f 63 63 75 72 2c 20 74 68 65 79 20 77  rs occur, they w
34540 69 6c 6c 20 6c 69 6b 65 6c 79 20 6f 63 63 75 72  ill likely occur
34550 0a 2a 2a 20 61 74 20 74 68 65 20 74 69 6d 65 20  .** at the time 
34560 77 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73  when the BLOB is
34570 20 63 6c 6f 73 65 64 2e 20 20 41 6e 79 20 65 72   closed.  Any er
34580 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
34590 64 75 72 69 6e 67 0a 2a 2a 20 63 6c 6f 73 69 6e  during.** closin
345a0 67 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 61  g are reported a
345b0 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74  s a non-zero ret
345c0 75 72 6e 20 76 61 6c 75 65 2e 29 5e 0a 2a 2a 0a  urn value.)^.**.
345d0 2a 2a 20 5e 28 54 68 65 20 42 4c 4f 42 20 69 73  ** ^(The BLOB is
345e0 20 63 6c 6f 73 65 64 20 75 6e 63 6f 6e 64 69 74   closed uncondit
345f0 69 6f 6e 61 6c 6c 79 2e 20 20 45 76 65 6e 20 69  ionally.  Even i
34600 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  f this routine r
34610 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 20 65 72 72  eturns.** an err
34620 6f 72 20 63 6f 64 65 2c 20 74 68 65 20 42 4c 4f  or code, the BLO
34630 42 20 69 73 20 73 74 69 6c 6c 20 63 6c 6f 73 65  B is still close
34640 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  d.)^.**.** ^Call
34650 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
34660 20 77 69 74 68 20 61 20 6e 75 6c 6c 20 70 6f 69   with a null poi
34670 6e 74 65 72 20 28 73 75 63 68 20 61 73 20 77 6f  nter (such as wo
34680 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 0a  uld be returned.
34690 2a 2a 20 62 79 20 61 20 66 61 69 6c 65 64 20 63  ** by a failed c
346a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
346b0 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 29 20 69 73  blob_open()]) is
346c0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
346d0 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
346e0 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 73 71 6c  3_blob_close(sql
346f0 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a 2f  ite3_blob *);../
34700 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
34710 65 74 75 72 6e 20 54 68 65 20 53 69 7a 65 20 4f  eturn The Size O
34720 66 20 41 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a  f An Open BLOB.*
34730 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 73 20 74 68  *.** ^Returns th
34740 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20  e size in bytes 
34750 6f 66 20 74 68 65 20 42 4c 4f 42 20 61 63 63 65  of the BLOB acce
34760 73 73 69 62 6c 65 20 76 69 61 20 74 68 65 20 0a  ssible via the .
34770 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20  ** successfully 
34780 6f 70 65 6e 65 64 20 5b 42 4c 4f 42 20 68 61 6e  opened [BLOB han
34790 64 6c 65 5d 20 69 6e 20 69 74 73 20 6f 6e 6c 79  dle] in its only
347a0 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
347b0 0a 2a 2a 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  .** incremental 
347c0 62 6c 6f 62 20 49 2f 4f 20 72 6f 75 74 69 6e 65  blob I/O routine
347d0 73 20 63 61 6e 20 6f 6e 6c 79 20 72 65 61 64 20  s can only read 
347e0 6f 72 20 6f 76 65 72 77 72 69 74 69 6e 67 20 65  or overwriting e
347f0 78 69 73 74 69 6e 67 0a 2a 2a 20 62 6c 6f 62 20  xisting.** blob 
34800 63 6f 6e 74 65 6e 74 3b 20 74 68 65 79 20 63 61  content; they ca
34810 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
34820 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 2e 0a  size of a blob..
34830 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
34840 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e  ne only works on
34850 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d   a [BLOB handle]
34860 20 77 68 69 63 68 20 68 61 73 20 62 65 65 6e 20   which has been 
34870 63 72 65 61 74 65 64 0a 2a 2a 20 62 79 20 61 20  created.** by a 
34880 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
34890 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
348a0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61  3_blob_open()] a
348b0 6e 64 20 77 68 69 63 68 20 68 61 73 20 6e 6f 74  nd which has not
348c0 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73 65 64 20  .** been closed 
348d0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
348e0 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50 61 73 73  _close()].  Pass
348f0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 70 6f  ing any other po
34900 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74  inter in.** to t
34910 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 73 75  his routine resu
34920 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
34930 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
34940 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
34950 6f 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  or..*/.int sqlit
34960 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 73 71  e3_blob_bytes(sq
34970 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 29 3b 0a 0a  lite3_blob *);..
34980 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34990 52 65 61 64 20 44 61 74 61 20 46 72 6f 6d 20 41  Read Data From A
349a0 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e 74 61   BLOB Incrementa
349b0 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  lly.**.** ^(This
349c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65   function is use
349d0 64 20 74 6f 20 72 65 61 64 20 64 61 74 61 20 66  d to read data f
349e0 72 6f 6d 20 61 6e 20 6f 70 65 6e 20 5b 42 4c 4f  rom an open [BLO
349f0 42 20 68 61 6e 64 6c 65 5d 20 69 6e 74 6f 20 61  B handle] into a
34a00 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70 70 6c  .** caller-suppl
34a10 69 65 64 20 62 75 66 66 65 72 2e 20 4e 20 62 79  ied buffer. N by
34a20 74 65 73 20 6f 66 20 64 61 74 61 20 61 72 65 20  tes of data are 
34a30 63 6f 70 69 65 64 20 69 6e 74 6f 20 62 75 66 66  copied into buff
34a40 65 72 20 5a 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  er Z.** from the
34a50 20 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72   open BLOB, star
34a60 74 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69  ting at offset i
34a70 4f 66 66 73 65 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  Offset.)^.**.** 
34a80 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66 66 73  ^If offset iOffs
34a90 65 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  et is less than 
34aa0 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74 68 65  N bytes from the
34ab0 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c 4f 42   end of the BLOB
34ac0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  ,.** [SQLITE_ERR
34ad0 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
34ae0 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72  and no data is r
34af0 65 61 64 2e 20 20 5e 49 66 20 4e 20 6f 72 20 69  ead.  ^If N or i
34b00 4f 66 66 73 65 74 20 69 73 0a 2a 2a 20 6c 65 73  Offset is.** les
34b10 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 5b 53 51  s than zero, [SQ
34b20 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
34b30 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
34b40 61 74 61 20 69 73 20 72 65 61 64 2e 0a 2a 2a 20  ata is read..** 
34b50 5e 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65  ^The size of the
34b60 20 62 6c 6f 62 20 28 61 6e 64 20 68 65 6e 63 65   blob (and hence
34b70 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 76 61 6c   the maximum val
34b80 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73 65 74 29  ue of N+iOffset)
34b90 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72  .** can be deter
34ba0 6d 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20  mined using the 
34bb0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79  [sqlite3_blob_by
34bc0 74 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tes()] interface
34bd0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 74 74 65  ..**.** ^An atte
34be0 6d 70 74 20 74 6f 20 72 65 61 64 20 66 72 6f 6d  mpt to read from
34bf0 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42 4c 4f   an expired [BLO
34c00 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c 73 20  B handle] fails 
34c10 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72 6f 72  with an.** error
34c20 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45   code of [SQLITE
34c30 5f 41 42 4f 52 54 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  _ABORT]..**.** ^
34c40 28 4f 6e 20 73 75 63 63 65 73 73 2c 20 73 71 6c  (On success, sql
34c50 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
34c60 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
34c70 4f 4b 2e 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65  OK..** Otherwise
34c80 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  , an [error code
34c90 5d 20 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65  ] or an [extende
34ca0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73  d error code] is
34cb0 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
34cc0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
34cd0 6f 6e 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20  only works on a 
34ce0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68  [BLOB handle] wh
34cf0 69 63 68 20 68 61 73 20 62 65 65 6e 20 63 72 65  ich has been cre
34d00 61 74 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69  ated.** by a pri
34d10 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
34d20 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  ll to [sqlite3_b
34d30 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20  lob_open()] and 
34d40 77 68 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a  which has not.**
34d50 20 62 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20   been closed by 
34d60 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
34d70 6f 73 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67  ose()].  Passing
34d80 20 61 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74   any other point
34d90 65 72 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73  er in.** to this
34da0 20 72 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73   routine results
34db0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   in undefined an
34dc0 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
34dd0 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e  irable behavior.
34de0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
34df0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
34e00 72 69 74 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rite()]..*/.int 
34e10 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
34e20 64 28 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a  d(sqlite3_blob *
34e30 2c 20 76 6f 69 64 20 2a 5a 2c 20 69 6e 74 20 4e  , void *Z, int N
34e40 2c 20 69 6e 74 20 69 4f 66 66 73 65 74 29 3b 0a  , int iOffset);.
34e50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34e60 20 57 72 69 74 65 20 44 61 74 61 20 49 6e 74 6f   Write Data Into
34e70 20 41 20 42 4c 4f 42 20 49 6e 63 72 65 6d 65 6e   A BLOB Incremen
34e80 74 61 6c 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  tally.**.** ^Thi
34e90 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  s function is us
34ea0 65 64 20 74 6f 20 77 72 69 74 65 20 64 61 74 61  ed to write data
34eb0 20 69 6e 74 6f 20 61 6e 20 6f 70 65 6e 20 5b 42   into an open [B
34ec0 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 72 6f 6d  LOB handle] from
34ed0 20 61 0a 2a 2a 20 63 61 6c 6c 65 72 2d 73 75 70   a.** caller-sup
34ee0 70 6c 69 65 64 20 62 75 66 66 65 72 2e 20 5e 4e  plied buffer. ^N
34ef0 20 62 79 74 65 73 20 6f 66 20 64 61 74 61 20 61   bytes of data a
34f00 72 65 20 63 6f 70 69 65 64 20 66 72 6f 6d 20 74  re copied from t
34f10 68 65 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20 69  he buffer Z.** i
34f20 6e 74 6f 20 74 68 65 20 6f 70 65 6e 20 42 4c 4f  nto the open BLO
34f30 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20 6f  B, starting at o
34f40 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 0a 2a  ffset iOffset..*
34f50 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 42 4c  *.** ^If the [BL
34f60 4f 42 20 68 61 6e 64 6c 65 5d 20 70 61 73 73 65  OB handle] passe
34f70 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
34f80 72 67 75 6d 65 6e 74 20 77 61 73 20 6e 6f 74 20  rgument was not 
34f90 6f 70 65 6e 65 64 20 66 6f 72 0a 2a 2a 20 77 72  opened for.** wr
34fa0 69 74 69 6e 67 20 28 74 68 65 20 66 6c 61 67 73  iting (the flags
34fb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
34fc0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
34fd0 28 29 5d 20 77 61 73 20 7a 65 72 6f 29 2c 0a 2a  ()] was zero),.*
34fe0 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * this function 
34ff0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
35000 52 45 41 44 4f 4e 4c 59 5d 2e 0a 2a 2a 0a 2a 2a  READONLY]..**.**
35010 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
35020 6d 61 79 20 6f 6e 6c 79 20 6d 6f 64 69 66 79 20  may only modify 
35030 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  the contents of 
35040 74 68 65 20 42 4c 4f 42 3b 20 69 74 20 69 73 0a  the BLOB; it is.
35050 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
35060 74 6f 20 69 6e 63 72 65 61 73 65 20 74 68 65 20  to increase the 
35070 73 69 7a 65 20 6f 66 20 61 20 42 4c 4f 42 20 75  size of a BLOB u
35080 73 69 6e 67 20 74 68 69 73 20 41 50 49 2e 0a 2a  sing this API..*
35090 2a 20 5e 49 66 20 6f 66 66 73 65 74 20 69 4f 66  * ^If offset iOf
350a0 66 73 65 74 20 69 73 20 6c 65 73 73 20 74 68 61  fset is less tha
350b0 6e 20 4e 20 62 79 74 65 73 20 66 72 6f 6d 20 74  n N bytes from t
350c0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 42 4c  he end of the BL
350d0 4f 42 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  OB,.** [SQLITE_E
350e0 52 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65  RROR] is returne
350f0 64 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73  d and no data is
35100 20 77 72 69 74 74 65 6e 2e 20 20 5e 49 66 20 4e   written.  ^If N
35110 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e   is.** less than
35120 20 7a 65 72 6f 20 5b 53 51 4c 49 54 45 5f 45 52   zero [SQLITE_ER
35130 52 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ROR] is returned
35140 20 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20   and no data is 
35150 77 72 69 74 74 65 6e 2e 0a 2a 2a 20 54 68 65 20  written..** The 
35160 73 69 7a 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  size of the BLOB
35170 20 28 61 6e 64 20 68 65 6e 63 65 20 74 68 65 20   (and hence the 
35180 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66  maximum value of
35190 20 4e 2b 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63   N+iOffset).** c
351a0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
351b0 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69   using the [sqli
351c0 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29  te3_blob_bytes()
351d0 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  ] interface..**.
351e0 2a 2a 20 5e 41 6e 20 61 74 74 65 6d 70 74 20 74  ** ^An attempt t
351f0 6f 20 77 72 69 74 65 20 74 6f 20 61 6e 20 65 78  o write to an ex
35200 70 69 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64  pired [BLOB hand
35210 6c 65 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61  le] fails with a
35220 6e 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  n.** error code 
35230 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  of [SQLITE_ABORT
35240 5d 2e 20 20 5e 57 72 69 74 65 73 20 74 6f 20 74  ].  ^Writes to t
35250 68 65 20 42 4c 4f 42 20 74 68 61 74 20 6f 63 63  he BLOB that occ
35260 75 72 72 65 64 0a 2a 2a 20 62 65 66 6f 72 65 20  urred.** before 
35270 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  the [BLOB handle
35280 5d 20 65 78 70 69 72 65 64 20 61 72 65 20 6e 6f  ] expired are no
35290 74 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 79  t rolled back by
352a0 20 74 68 65 0a 2a 2a 20 65 78 70 69 72 61 74 69   the.** expirati
352b0 6f 6e 20 6f 66 20 74 68 65 20 68 61 6e 64 6c 65  on of the handle
352c0 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
352d0 73 65 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  se those changes
352e0 20 6d 69 67 68 74 0a 2a 2a 20 68 61 76 65 20 62   might.** have b
352f0 65 65 6e 20 6f 76 65 72 77 72 69 74 74 65 6e 20  een overwritten 
35300 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  by the statement
35310 20 74 68 61 74 20 65 78 70 69 72 65 64 20 74 68   that expired th
35320 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 0a 2a 2a  e BLOB handle.**
35330 20 6f 72 20 62 79 20 6f 74 68 65 72 20 69 6e 64   or by other ind
35340 65 70 65 6e 64 65 6e 74 20 73 74 61 74 65 6d 65  ependent stateme
35350 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20  nts..**.** ^(On 
35360 73 75 63 63 65 73 73 2c 20 73 71 6c 69 74 65 33  success, sqlite3
35370 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 20 72 65  _blob_write() re
35380 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2e  turns SQLITE_OK.
35390 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 61  .** Otherwise, a
353a0 6e 20 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  n  [error code] 
353b0 6f 72 20 61 6e 20 5b 65 78 74 65 6e 64 65 64 20  or an [extended 
353c0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
353d0 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
353e0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e   This routine on
353f0 6c 79 20 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42  ly works on a [B
35400 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 77 68 69 63  LOB handle] whic
35410 68 20 68 61 73 20 62 65 65 6e 20 63 72 65 61 74  h has been creat
35420 65 64 0a 2a 2a 20 62 79 20 61 20 70 72 69 6f 72  ed.** by a prior
35430 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
35440 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f   to [sqlite3_blo
35450 62 5f 6f 70 65 6e 28 29 5d 20 61 6e 64 20 77 68  b_open()] and wh
35460 69 63 68 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62  ich has not.** b
35470 65 65 6e 20 63 6c 6f 73 65 64 20 62 79 20 5b 73  een closed by [s
35480 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
35490 65 28 29 5d 2e 20 20 50 61 73 73 69 6e 67 20 61  e()].  Passing a
354a0 6e 79 20 6f 74 68 65 72 20 70 6f 69 6e 74 65 72  ny other pointer
354b0 20 69 6e 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72   in.** to this r
354c0 6f 75 74 69 6e 65 20 72 65 73 75 6c 74 73 20 69  outine results i
354d0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  n undefined and 
354e0 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
354f0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a  able behavior..*
35500 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
35510 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61  sqlite3_blob_rea
35520 64 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  d()]..*/.int sql
35530 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28  ite3_blob_write(
35540 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a 2c 20  sqlite3_blob *, 
35550 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 2c 20 69  const void *z, i
35560 6e 74 20 6e 2c 20 69 6e 74 20 69 4f 66 66 73 65  nt n, int iOffse
35570 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
35580 52 45 46 3a 20 56 69 72 74 75 61 6c 20 46 69 6c  REF: Virtual Fil
35590 65 20 53 79 73 74 65 6d 20 4f 62 6a 65 63 74 73  e System Objects
355a0 0a 2a 2a 0a 2a 2a 20 41 20 76 69 72 74 75 61 6c  .**.** A virtual
355b0 20 66 69 6c 65 73 79 73 74 65 6d 20 28 56 46 53   filesystem (VFS
355c0 29 20 69 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  ) is an [sqlite3
355d0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  _vfs] object.** 
355e0 74 68 61 74 20 53 51 4c 69 74 65 20 75 73 65 73  that SQLite uses
355f0 20 74 6f 20 69 6e 74 65 72 61 63 74 0a 2a 2a 20   to interact.** 
35600 77 69 74 68 20 74 68 65 20 75 6e 64 65 72 6c 79  with the underly
35610 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
35620 73 74 65 6d 2e 20 20 4d 6f 73 74 20 53 51 4c 69  stem.  Most SQLi
35630 74 65 20 62 75 69 6c 64 73 20 63 6f 6d 65 20 77  te builds come w
35640 69 74 68 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20  ith a.** single 
35650 64 65 66 61 75 6c 74 20 56 46 53 20 74 68 61 74  default VFS that
35660 20 69 73 20 61 70 70 72 6f 70 72 69 61 74 65 20   is appropriate 
35670 66 6f 72 20 74 68 65 20 68 6f 73 74 20 63 6f 6d  for the host com
35680 70 75 74 65 72 2e 0a 2a 2a 20 4e 65 77 20 56 46  puter..** New VF
35690 53 65 73 20 63 61 6e 20 62 65 20 72 65 67 69 73  Ses can be regis
356a0 74 65 72 65 64 20 61 6e 64 20 65 78 69 73 74 69  tered and existi
356b0 6e 67 20 56 46 53 65 73 20 63 61 6e 20 62 65 20  ng VFSes can be 
356c0 75 6e 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  unregistered..**
356d0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 69   The following i
356e0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
356f0 6f 76 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ovided..**.** ^T
35700 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  he sqlite3_vfs_f
35710 69 6e 64 28 29 20 69 6e 74 65 72 66 61 63 65 20  ind() interface 
35720 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
35730 72 20 74 6f 20 61 20 56 46 53 20 67 69 76 65 6e  r to a VFS given
35740 20 69 74 73 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4e   its name..** ^N
35750 61 6d 65 73 20 61 72 65 20 63 61 73 65 20 73 65  ames are case se
35760 6e 73 69 74 69 76 65 2e 0a 2a 2a 20 5e 4e 61 6d  nsitive..** ^Nam
35770 65 73 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  es are zero-term
35780 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
35790 69 6e 67 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ings..** ^If the
357a0 72 65 20 69 73 20 6e 6f 20 6d 61 74 63 68 2c 20  re is no match, 
357b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
357c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
357d0 49 66 20 7a 56 66 73 4e 61 6d 65 20 69 73 20 4e  If zVfsName is N
357e0 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 64 65 66  ULL then the def
357f0 61 75 6c 74 20 56 46 53 20 69 73 20 72 65 74 75  ault VFS is retu
35800 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 65 77  rned..**.** ^New
35810 20 56 46 53 65 73 20 61 72 65 20 72 65 67 69 73   VFSes are regis
35820 74 65 72 65 64 20 77 69 74 68 20 73 71 6c 69 74  tered with sqlit
35830 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
35840 29 2e 0a 2a 2a 20 5e 45 61 63 68 20 6e 65 77 20  )..** ^Each new 
35850 56 46 53 20 62 65 63 6f 6d 65 73 20 74 68 65 20  VFS becomes the 
35860 64 65 66 61 75 6c 74 20 56 46 53 20 69 66 20 74  default VFS if t
35870 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67  he makeDflt flag
35880 20 69 73 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   is set..** ^The
35890 20 73 61 6d 65 20 56 46 53 20 63 61 6e 20 62 65   same VFS can be
358a0 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
358b0 69 70 6c 65 20 74 69 6d 65 73 20 77 69 74 68 6f  iple times witho
358c0 75 74 20 69 6e 6a 75 72 79 2e 0a 2a 2a 20 5e 54  ut injury..** ^T
358d0 6f 20 6d 61 6b 65 20 61 6e 20 65 78 69 73 74 69  o make an existi
358e0 6e 67 20 56 46 53 20 69 6e 74 6f 20 74 68 65 20  ng VFS into the 
358f0 64 65 66 61 75 6c 74 20 56 46 53 2c 20 72 65 67  default VFS, reg
35900 69 73 74 65 72 20 69 74 20 61 67 61 69 6e 0a 2a  ister it again.*
35910 2a 20 77 69 74 68 20 74 68 65 20 6d 61 6b 65 44  * with the makeD
35920 66 6c 74 20 66 6c 61 67 20 73 65 74 2e 20 20 49  flt flag set.  I
35930 66 20 74 77 6f 20 64 69 66 66 65 72 65 6e 74 20  f two different 
35940 56 46 53 65 73 20 77 69 74 68 20 74 68 65 0a 2a  VFSes with the.*
35950 2a 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  * same name are 
35960 72 65 67 69 73 74 65 72 65 64 2c 20 74 68 65 20  registered, the 
35970 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
35980 66 69 6e 65 64 2e 20 20 49 66 20 61 0a 2a 2a 20  fined.  If a.** 
35990 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72 65  VFS is registere
359a0 64 20 77 69 74 68 20 61 20 6e 61 6d 65 20 74 68  d with a name th
359b0 61 74 20 69 73 20 4e 55 4c 4c 20 6f 72 20 61 6e  at is NULL or an
359c0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 0a 2a   empty string,.*
359d0 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
359e0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
359f0 2e 0a 2a 2a 0a 2a 2a 20 5e 55 6e 72 65 67 69 73  ..**.** ^Unregis
35a00 74 65 72 20 61 20 56 46 53 20 77 69 74 68 20 74  ter a VFS with t
35a10 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  he sqlite3_vfs_u
35a20 6e 72 65 67 69 73 74 65 72 28 29 20 69 6e 74 65  nregister() inte
35a30 72 66 61 63 65 2e 0a 2a 2a 20 5e 28 49 66 20 74  rface..** ^(If t
35a40 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 69  he default VFS i
35a50 73 20 75 6e 72 65 67 69 73 74 65 72 65 64 2c 20  s unregistered, 
35a60 61 6e 6f 74 68 65 72 20 56 46 53 20 69 73 20 63  another VFS is c
35a70 68 6f 73 65 6e 20 61 73 0a 2a 2a 20 74 68 65 20  hosen as.** the 
35a80 64 65 66 61 75 6c 74 2e 20 20 54 68 65 20 63 68  default.  The ch
35a90 6f 69 63 65 20 66 6f 72 20 74 68 65 20 6e 65 77  oice for the new
35aa0 20 56 46 53 20 69 73 20 61 72 62 69 74 72 61 72   VFS is arbitrar
35ab0 79 2e 29 5e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  y.)^.*/.sqlite3_
35ac0 76 66 73 20 2a 73 71 6c 69 74 65 33 5f 76 66 73  vfs *sqlite3_vfs
35ad0 5f 66 69 6e 64 28 63 6f 6e 73 74 20 63 68 61 72  _find(const char
35ae0 20 2a 7a 56 66 73 4e 61 6d 65 29 3b 0a 69 6e 74   *zVfsName);.int
35af0 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67   sqlite3_vfs_reg
35b00 69 73 74 65 72 28 73 71 6c 69 74 65 33 5f 76 66  ister(sqlite3_vf
35b10 73 2a 2c 20 69 6e 74 20 6d 61 6b 65 44 66 6c 74  s*, int makeDflt
35b20 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
35b30 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 73 71  fs_unregister(sq
35b40 6c 69 74 65 33 5f 76 66 73 2a 29 3b 0a 0a 2f 2a  lite3_vfs*);../*
35b50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
35b60 74 65 78 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  texes.**.** The 
35b70 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73  SQLite core uses
35b80 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
35b90 66 6f 72 20 74 68 72 65 61 64 0a 2a 2a 20 73 79  for thread.** sy
35ba0 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 2e 20 54  nchronization. T
35bb0 68 6f 75 67 68 20 74 68 65 79 20 61 72 65 20 69  hough they are i
35bc0 6e 74 65 6e 64 65 64 20 66 6f 72 20 69 6e 74 65  ntended for inte
35bd0 72 6e 61 6c 0a 2a 2a 20 75 73 65 20 62 79 20 53  rnal.** use by S
35be0 51 4c 69 74 65 2c 20 63 6f 64 65 20 74 68 61 74  QLite, code that
35bf0 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 53   links against S
35c00 51 4c 69 74 65 20 69 73 0a 2a 2a 20 70 65 72 6d  QLite is.** perm
35c10 69 74 74 65 64 20 74 6f 20 75 73 65 20 61 6e 79  itted to use any
35c20 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
35c30 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  es..**.** The SQ
35c40 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65  Lite source code
35c50 20 63 6f 6e 74 61 69 6e 73 20 6d 75 6c 74 69 70   contains multip
35c60 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
35c70 6e 73 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 6d  ns.** of these m
35c80 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 20 20  utex routines.  
35c90 41 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 69  An appropriate i
35ca0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
35cb0 20 69 73 20 73 65 6c 65 63 74 65 64 20 61 75 74   is selected aut
35cc0 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 20 63 6f  omatically at co
35cd0 6d 70 69 6c 65 2d 74 69 6d 65 2e 20 20 5e 28 54  mpile-time.  ^(T
35ce0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  he following.** 
35cf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
35d00 61 72 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  are available in
35d10 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
35d20 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
35d30 3c 6c 69 3e 20 20 20 53 51 4c 49 54 45 5f 4d 55  <li>   SQLITE_MU
35d40 54 45 58 5f 4f 53 32 0a 2a 2a 20 3c 6c 69 3e 20  TEX_OS2.** <li> 
35d50 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50    SQLITE_MUTEX_P
35d60 54 48 52 45 41 44 0a 2a 2a 20 3c 6c 69 3e 20 20  THREAD.** <li>  
35d70 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 33   SQLITE_MUTEX_W3
35d80 32 0a 2a 2a 20 3c 6c 69 3e 20 20 20 53 51 4c 49  2.** <li>   SQLI
35d90 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f 50 0a 2a 2a  TE_MUTEX_NOOP.**
35da0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   </ul>)^.**.** ^
35db0 54 68 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  The SQLITE_MUTEX
35dc0 5f 4e 4f 4f 50 20 69 6d 70 6c 65 6d 65 6e 74 61  _NOOP implementa
35dd0 74 69 6f 6e 20 69 73 20 61 20 73 65 74 20 6f 66  tion is a set of
35de0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 74 68 61   routines.** tha
35df0 74 20 64 6f 65 73 20 6e 6f 20 72 65 61 6c 20 6c  t does no real l
35e00 6f 63 6b 69 6e 67 20 61 6e 64 20 69 73 20 61 70  ocking and is ap
35e10 70 72 6f 70 72 69 61 74 65 20 66 6f 72 20 75 73  propriate for us
35e20 65 20 69 6e 0a 2a 2a 20 61 20 73 69 6e 67 6c 65  e in.** a single
35e30 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
35e40 61 74 69 6f 6e 2e 20 20 5e 54 68 65 20 53 51 4c  ation.  ^The SQL
35e50 49 54 45 5f 4d 55 54 45 58 5f 4f 53 32 2c 0a 2a  ITE_MUTEX_OS2,.*
35e60 2a 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 50  * SQLITE_MUTEX_P
35e70 54 48 52 45 41 44 2c 20 61 6e 64 20 53 51 4c 49  THREAD, and SQLI
35e80 54 45 5f 4d 55 54 45 58 5f 57 33 32 20 69 6d 70  TE_MUTEX_W32 imp
35e90 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20  lementations.** 
35ea0 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  are appropriate 
35eb0 66 6f 72 20 75 73 65 20 6f 6e 20 4f 53 2f 32 2c  for use on OS/2,
35ec0 20 55 6e 69 78 2c 20 61 6e 64 20 57 69 6e 64 6f   Unix, and Windo
35ed0 77 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53  ws..**.** ^(If S
35ee0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
35ef0 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
35f00 45 5f 4d 55 54 45 58 5f 41 50 50 44 45 46 20 70  E_MUTEX_APPDEF p
35f10 72 65 70 72 6f 63 65 73 73 6f 72 0a 2a 2a 20 6d  reprocessor.** m
35f20 61 63 72 6f 20 64 65 66 69 6e 65 64 20 28 77 69  acro defined (wi
35f30 74 68 20 22 2d 44 53 51 4c 49 54 45 5f 4d 55 54  th "-DSQLITE_MUT
35f40 45 58 5f 41 50 50 44 45 46 3d 31 22 29 2c 20 74  EX_APPDEF=1"), t
35f50 68 65 6e 20 6e 6f 20 6d 75 74 65 78 0a 2a 2a 20  hen no mutex.** 
35f60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
35f70 73 20 69 6e 63 6c 75 64 65 64 20 77 69 74 68 20  s included with 
35f80 74 68 65 20 6c 69 62 72 61 72 79 2e 20 49 6e 20  the library. In 
35f90 74 68 69 73 20 63 61 73 65 20 74 68 65 0a 2a 2a  this case the.**
35fa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
35fb0 74 20 73 75 70 70 6c 79 20 61 20 63 75 73 74 6f  t supply a custo
35fc0 6d 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65 6e  m mutex implemen
35fd0 74 61 74 69 6f 6e 20 75 73 69 6e 67 20 74 68 65  tation using the
35fe0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
35ff0 49 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  IG_MUTEX] option
36000 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
36010 63 6f 6e 66 69 67 28 29 20 66 75 6e 63 74 69 6f  config() functio
36020 6e 0a 2a 2a 20 62 65 66 6f 72 65 20 63 61 6c 6c  n.** before call
36030 69 6e 67 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  ing sqlite3_init
36040 69 61 6c 69 7a 65 28 29 20 6f 72 20 61 6e 79 20  ialize() or any 
36050 6f 74 68 65 72 20 70 75 62 6c 69 63 20 73 71 6c  other public sql
36060 69 74 65 33 5f 0a 2a 2a 20 66 75 6e 63 74 69 6f  ite3_.** functio
36070 6e 20 74 68 61 74 20 63 61 6c 6c 73 20 73 71 6c  n that calls sql
36080 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
36090 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
360a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
360b0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 61 6c  loc() routine al
360c0 6c 6f 63 61 74 65 73 20 61 20 6e 65 77 0a 2a 2a  locates a new.**
360d0 20 6d 75 74 65 78 20 61 6e 64 20 72 65 74 75 72   mutex and retur
360e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
360f0 69 74 2e 20 5e 49 66 20 69 74 20 72 65 74 75 72  it. ^If it retur
36100 6e 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 61 74 20  ns NULL.** that 
36110 6d 65 61 6e 73 20 74 68 61 74 20 61 20 6d 75 74  means that a mut
36120 65 78 20 63 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ex could not be 
36130 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 53 51 4c  allocated.  ^SQL
36140 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 75 6e 77 69  ite.** will unwi
36150 6e 64 20 69 74 73 20 73 74 61 63 6b 20 61 6e 64  nd its stack and
36160 20 72 65 74 75 72 6e 20 61 6e 20 65 72 72 6f 72   return an error
36170 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e  .  ^(The argumen
36180 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
36190 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 69 73  mutex_alloc() is
361a0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
361b0 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 3a  teger constants:
361c0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
361d0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
361e0 58 5f 46 41 53 54 0a 2a 2a 20 3c 6c 69 3e 20 20  X_FAST.** <li>  
361f0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52 45 43  SQLITE_MUTEX_REC
36200 55 52 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  URSIVE.** <li>  
36210 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
36220 54 49 43 5f 4d 41 53 54 45 52 0a 2a 2a 20 3c 6c  TIC_MASTER.** <l
36230 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  i>  SQLITE_MUTEX
36240 5f 53 54 41 54 49 43 5f 4d 45 4d 0a 2a 2a 20 3c  _STATIC_MEM.** <
36250 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55 54 45  li>  SQLITE_MUTE
36260 58 5f 53 54 41 54 49 43 5f 4d 45 4d 32 0a 2a 2a  X_STATIC_MEM2.**
36270 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 4d 55   <li>  SQLITE_MU
36280 54 45 58 5f 53 54 41 54 49 43 5f 50 52 4e 47 0a  TEX_STATIC_PRNG.
36290 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
362a0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
362b0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
362c0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52  _MUTEX_STATIC_LR
362d0 55 32 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  U2.** </ul>)^.**
362e0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
362f0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 28 53 51  wo constants (SQ
36300 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 20  LITE_MUTEX_FAST 
36310 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54 45 58  and SQLITE_MUTEX
36320 5f 52 45 43 55 52 53 49 56 45 29 0a 2a 2a 20 63  _RECURSIVE).** c
36330 61 75 73 65 20 73 71 6c 69 74 65 33 5f 6d 75 74  ause sqlite3_mut
36340 65 78 5f 61 6c 6c 6f 63 28 29 20 74 6f 20 63 72  ex_alloc() to cr
36350 65 61 74 65 0a 2a 2a 20 61 20 6e 65 77 20 6d 75  eate.** a new mu
36360 74 65 78 2e 20 20 5e 54 68 65 20 6e 65 77 20 6d  tex.  ^The new m
36370 75 74 65 78 20 69 73 20 72 65 63 75 72 73 69 76  utex is recursiv
36380 65 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55  e when SQLITE_MU
36390 54 45 58 5f 52 45 43 55 52 53 49 56 45 0a 2a 2a  TEX_RECURSIVE.**
363a0 20 69 73 20 75 73 65 64 20 62 75 74 20 6e 6f 74   is used but not
363b0 20 6e 65 63 65 73 73 61 72 69 6c 79 20 73 6f 20   necessarily so 
363c0 77 68 65 6e 20 53 51 4c 49 54 45 5f 4d 55 54 45  when SQLITE_MUTE
363d0 58 5f 46 41 53 54 20 69 73 20 75 73 65 64 2e 0a  X_FAST is used..
363e0 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 69 6d 70  ** The mutex imp
363f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 64 6f 65 73  lementation does
36400 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 6d 61 6b   not need to mak
36410 65 20 61 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a  e a distinction.
36420 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54  ** between SQLIT
36430 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56  E_MUTEX_RECURSIV
36440 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4d 55 54  E and SQLITE_MUT
36450 45 58 5f 46 41 53 54 20 69 66 20 69 74 20 64 6f  EX_FAST if it do
36460 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
36470 6f 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  o.  ^SQLite will
36480 20 6f 6e 6c 79 20 72 65 71 75 65 73 74 20 61 20   only request a 
36490 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 20  recursive mutex 
364a0 69 6e 0a 2a 2a 20 63 61 73 65 73 20 77 68 65 72  in.** cases wher
364b0 65 20 69 74 20 72 65 61 6c 6c 79 20 6e 65 65 64  e it really need
364c0 73 20 6f 6e 65 2e 20 20 5e 49 66 20 61 20 66 61  s one.  ^If a fa
364d0 73 74 65 72 20 6e 6f 6e 2d 72 65 63 75 72 73 69  ster non-recursi
364e0 76 65 20 6d 75 74 65 78 0a 2a 2a 20 69 6d 70 6c  ve mutex.** impl
364f0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 61 76  ementation is av
36500 61 69 6c 61 62 6c 65 20 6f 6e 20 74 68 65 20 68  ailable on the h
36510 6f 73 74 20 70 6c 61 74 66 6f 72 6d 2c 20 74 68  ost platform, th
36520 65 20 6d 75 74 65 78 20 73 75 62 73 79 73 74 65  e mutex subsyste
36530 6d 0a 2a 2a 20 6d 69 67 68 74 20 72 65 74 75 72  m.** might retur
36540 6e 20 73 75 63 68 20 61 20 6d 75 74 65 78 20 69  n such a mutex i
36550 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 53 51  n response to SQ
36560 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41 53 54 2e  LITE_MUTEX_FAST.
36570 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 74 68 65  .**.** ^The othe
36580 72 20 61 6c 6c 6f 77 65 64 20 70 61 72 61 6d 65  r allowed parame
36590 74 65 72 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  ters to sqlite3_
365a0 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 20 28 61  mutex_alloc() (a
365b0 6e 79 74 68 69 6e 67 20 6f 74 68 65 72 0a 2a 2a  nything other.**
365c0 20 74 68 61 6e 20 53 51 4c 49 54 45 5f 4d 55 54   than SQLITE_MUT
365d0 45 58 5f 46 41 53 54 20 61 6e 64 20 53 51 4c 49  EX_FAST and SQLI
365e0 54 45 5f 4d 55 54 45 58 5f 52 45 43 55 52 53 49  TE_MUTEX_RECURSI
365f0 56 45 29 20 65 61 63 68 20 72 65 74 75 72 6e 0a  VE) each return.
36600 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
36610 61 20 73 74 61 74 69 63 20 70 72 65 65 78 69 73  a static preexis
36620 74 69 6e 67 20 6d 75 74 65 78 2e 20 20 5e 53 69  ting mutex.  ^Si
36630 78 20 73 74 61 74 69 63 20 6d 75 74 65 78 65 73  x static mutexes
36640 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 62 79 20   are.** used by 
36650 74 68 65 20 63 75 72 72 65 6e 74 20 76 65 72 73  the current vers
36660 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ion of SQLite.  
36670 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
36680 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 61 79  of SQLite.** may
36690 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61 6c 20   add additional 
366a0 73 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 20  static mutexes. 
366b0 20 53 74 61 74 69 63 20 6d 75 74 65 78 65 73 20   Static mutexes 
366c0 61 72 65 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c  are for internal
366d0 0a 2a 2a 20 75 73 65 20 62 79 20 53 51 4c 69 74  .** use by SQLit
366e0 65 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61  e only.  Applica
366f0 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 53  tions that use S
36700 51 4c 69 74 65 20 6d 75 74 65 78 65 73 20 73 68  QLite mutexes sh
36710 6f 75 6c 64 0a 2a 2a 20 75 73 65 20 6f 6e 6c 79  ould.** use only
36720 20 74 68 65 20 64 79 6e 61 6d 69 63 20 6d 75 74   the dynamic mut
36730 65 78 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  exes returned by
36740 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 46 41   SQLITE_MUTEX_FA
36750 53 54 20 6f 72 0a 2a 2a 20 53 51 4c 49 54 45 5f  ST or.** SQLITE_
36760 4d 55 54 45 58 5f 52 45 43 55 52 53 49 56 45 2e  MUTEX_RECURSIVE.
36770 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
36780 74 20 69 66 20 6f 6e 65 20 6f 66 20 74 68 65 20  t if one of the 
36790 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 70 61  dynamic mutex pa
367a0 72 61 6d 65 74 65 72 73 20 28 53 51 4c 49 54 45  rameters (SQLITE
367b0 5f 4d 55 54 45 58 5f 46 41 53 54 0a 2a 2a 20 6f  _MUTEX_FAST.** o
367c0 72 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  r SQLITE_MUTEX_R
367d0 45 43 55 52 53 49 56 45 29 20 69 73 20 75 73 65  ECURSIVE) is use
367e0 64 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  d then sqlite3_m
367f0 75 74 65 78 5f 61 6c 6c 6f 63 28 29 0a 2a 2a 20  utex_alloc().** 
36800 72 65 74 75 72 6e 73 20 61 20 64 69 66 66 65 72  returns a differ
36810 65 6e 74 20 6d 75 74 65 78 20 6f 6e 20 65 76 65  ent mutex on eve
36820 72 79 20 63 61 6c 6c 2e 20 20 5e 42 75 74 20 66  ry call.  ^But f
36830 6f 72 20 74 68 65 20 73 74 61 74 69 63 0a 2a 2a  or the static.**
36840 20 6d 75 74 65 78 20 74 79 70 65 73 2c 20 74 68   mutex types, th
36850 65 20 73 61 6d 65 20 6d 75 74 65 78 20 69 73 20  e same mutex is 
36860 72 65 74 75 72 6e 65 64 20 6f 6e 20 65 76 65 72  returned on ever
36870 79 20 63 61 6c 6c 20 74 68 61 74 20 68 61 73 0a  y call that has.
36880 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 79 70 65  ** the same type
36890 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e   number..**.** ^
368a0 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  The sqlite3_mute
368b0 78 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  x_free() routine
368c0 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 20 70   deallocates a p
368d0 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 61 6c 6c  reviously.** all
368e0 6f 63 61 74 65 64 20 64 79 6e 61 6d 69 63 20 6d  ocated dynamic m
368f0 75 74 65 78 2e 20 20 5e 53 51 4c 69 74 65 20 69  utex.  ^SQLite i
36900 73 20 63 61 72 65 66 75 6c 20 74 6f 20 64 65 61  s careful to dea
36910 6c 6c 6f 63 61 74 65 20 65 76 65 72 79 0a 2a 2a  llocate every.**
36920 20 64 79 6e 61 6d 69 63 20 6d 75 74 65 78 20 74   dynamic mutex t
36930 68 61 74 20 69 74 20 61 6c 6c 6f 63 61 74 65 73  hat it allocates
36940 2e 20 20 54 68 65 20 64 79 6e 61 6d 69 63 20 6d  .  The dynamic m
36950 75 74 65 78 65 73 20 6d 75 73 74 20 6e 6f 74 20  utexes must not 
36960 62 65 20 69 6e 0a 2a 2a 20 75 73 65 20 77 68 65  be in.** use whe
36970 6e 20 74 68 65 79 20 61 72 65 20 64 65 61 6c 6c  n they are deall
36980 6f 63 61 74 65 64 2e 20 20 41 74 74 65 6d 70 74  ocated.  Attempt
36990 69 6e 67 20 74 6f 20 64 65 61 6c 6c 6f 63 61 74  ing to deallocat
369a0 65 20 61 20 73 74 61 74 69 63 0a 2a 2a 20 6d 75  e a static.** mu
369b0 74 65 78 20 72 65 73 75 6c 74 73 20 69 6e 20 75  tex results in u
369c0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
369d0 72 2e 20 20 5e 53 51 4c 69 74 65 20 6e 65 76 65  r.  ^SQLite neve
369e0 72 20 64 65 61 6c 6c 6f 63 61 74 65 73 0a 2a 2a  r deallocates.**
369f0 20 61 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e   a static mutex.
36a00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36a10 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28  te3_mutex_enter(
36a20 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6d 75  ) and sqlite3_mu
36a30 74 65 78 5f 74 72 79 28 29 20 72 6f 75 74 69 6e  tex_try() routin
36a40 65 73 20 61 74 74 65 6d 70 74 0a 2a 2a 20 74 6f  es attempt.** to
36a50 20 65 6e 74 65 72 20 61 20 6d 75 74 65 78 2e 20   enter a mutex. 
36a60 20 5e 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72   ^If another thr
36a70 65 61 64 20 69 73 20 61 6c 72 65 61 64 79 20 77  ead is already w
36a80 69 74 68 69 6e 20 74 68 65 20 6d 75 74 65 78 2c  ithin the mutex,
36a90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
36aa0 78 5f 65 6e 74 65 72 28 29 20 77 69 6c 6c 20 62  x_enter() will b
36ab0 6c 6f 63 6b 20 61 6e 64 20 73 71 6c 69 74 65 33  lock and sqlite3
36ac0 5f 6d 75 74 65 78 5f 74 72 79 28 29 20 77 69 6c  _mutex_try() wil
36ad0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  l return.** SQLI
36ae0 54 45 5f 42 55 53 59 2e 20 20 5e 54 68 65 20 73  TE_BUSY.  ^The s
36af0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74 72 79  qlite3_mutex_try
36b00 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
36b10 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
36b20 0a 2a 2a 20 75 70 6f 6e 20 73 75 63 63 65 73 73  .** upon success
36b30 66 75 6c 20 65 6e 74 72 79 2e 20 20 5e 28 4d 75  ful entry.  ^(Mu
36b40 74 65 78 65 73 20 63 72 65 61 74 65 64 20 75 73  texes created us
36b50 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 4d 55  ing.** SQLITE_MU
36b60 54 45 58 5f 52 45 43 55 52 53 49 56 45 20 63 61  TEX_RECURSIVE ca
36b70 6e 20 62 65 20 65 6e 74 65 72 65 64 20 6d 75 6c  n be entered mul
36b80 74 69 70 6c 65 20 74 69 6d 65 73 20 62 79 20 74  tiple times by t
36b90 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 2e 0a  he same thread..
36ba0 2a 2a 20 49 6e 20 73 75 63 68 20 63 61 73 65 73  ** In such cases
36bb0 20 74 68 65 2c 0a 2a 2a 20 6d 75 74 65 78 20 6d   the,.** mutex m
36bc0 75 73 74 20 62 65 20 65 78 69 74 65 64 20 61 6e  ust be exited an
36bd0 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66   equal number of
36be0 20 74 69 6d 65 73 20 62 65 66 6f 72 65 20 61 6e   times before an
36bf0 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
36c00 63 61 6e 20 65 6e 74 65 72 2e 29 5e 20 20 5e 28  can enter.)^  ^(
36c10 49 66 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  If the same thre
36c20 61 64 20 74 72 69 65 73 20 74 6f 20 65 6e 74 65  ad tries to ente
36c30 72 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6b  r any other.** k
36c40 69 6e 64 20 6f 66 20 6d 75 74 65 78 20 6d 6f 72  ind of mutex mor
36c50 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 74 68 65  e than once, the
36c60 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
36c70 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 69 74  efined..** SQLit
36c80 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 65 78 68  e will never exh
36c90 69 62 69 74 0a 2a 2a 20 73 75 63 68 20 62 65 68  ibit.** such beh
36ca0 61 76 69 6f 72 20 69 6e 20 69 74 73 20 6f 77 6e  avior in its own
36cb0 20 75 73 65 20 6f 66 20 6d 75 74 65 78 65 73 2e   use of mutexes.
36cc0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 53 6f 6d 65 20  )^.**.** ^(Some 
36cd0 73 79 73 74 65 6d 73 20 28 66 6f 72 20 65 78 61  systems (for exa
36ce0 6d 70 6c 65 2c 20 57 69 6e 64 6f 77 73 20 39 35  mple, Windows 95
36cf0 29 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74  ) do not support
36d00 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a   the operation.*
36d10 2a 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  * implemented by
36d20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 74   sqlite3_mutex_t
36d30 72 79 28 29 2e 20 20 4f 6e 20 74 68 6f 73 65 20  ry().  On those 
36d40 73 79 73 74 65 6d 73 2c 20 73 71 6c 69 74 65 33  systems, sqlite3
36d50 5f 6d 75 74 65 78 5f 74 72 79 28 29 0a 2a 2a 20  _mutex_try().** 
36d60 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
36d70 72 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20  rn SQLITE_BUSY. 
36d80 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
36d90 20 6f 6e 6c 79 20 65 76 65 72 20 75 73 65 73 0a   only ever uses.
36da0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ** sqlite3_mutex
36db0 5f 74 72 79 28 29 20 61 73 20 61 6e 20 6f 70 74  _try() as an opt
36dc0 69 6d 69 7a 61 74 69 6f 6e 20 73 6f 20 74 68 69  imization so thi
36dd0 73 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20  s is acceptable 
36de0 62 65 68 61 76 69 6f 72 2e 29 5e 0a 2a 2a 0a 2a  behavior.)^.**.*
36df0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
36e00 75 74 65 78 5f 6c 65 61 76 65 28 29 20 72 6f 75  utex_leave() rou
36e10 74 69 6e 65 20 65 78 69 74 73 20 61 20 6d 75 74  tine exits a mut
36e20 65 78 20 74 68 61 74 20 77 61 73 0a 2a 2a 20 70  ex that was.** p
36e30 72 65 76 69 6f 75 73 6c 79 20 65 6e 74 65 72 65  reviously entere
36e40 64 20 62 79 20 74 68 65 20 73 61 6d 65 20 74 68  d by the same th
36e50 72 65 61 64 2e 20 20 20 5e 28 54 68 65 20 62 65  read.   ^(The be
36e60 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
36e70 65 66 69 6e 65 64 20 69 66 20 74 68 65 20 6d 75  efined if the mu
36e80 74 65 78 20 69 73 20 6e 6f 74 20 63 75 72 72 65  tex is not curre
36e90 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 62 79 20  ntly entered by 
36ea0 74 68 65 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 74  the.** calling t
36eb0 68 72 65 61 64 20 6f 72 20 69 73 20 6e 6f 74 20  hread or is not 
36ec0 63 75 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 63 61  currently alloca
36ed0 74 65 64 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ted.  SQLite wil
36ee0 6c 0a 2a 2a 20 6e 65 76 65 72 20 64 6f 20 65 69  l.** never do ei
36ef0 74 68 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ther.)^.**.** ^I
36f00 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  f the argument t
36f10 6f 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  o sqlite3_mutex_
36f20 65 6e 74 65 72 28 29 2c 20 73 71 6c 69 74 65 33  enter(), sqlite3
36f30 5f 6d 75 74 65 78 5f 74 72 79 28 29 2c 20 6f 72  _mutex_try(), or
36f40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  .** sqlite3_mute
36f50 78 5f 6c 65 61 76 65 28 29 20 69 73 20 61 20 4e  x_leave() is a N
36f60 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
36f70 6e 20 61 6c 6c 20 74 68 72 65 65 20 72 6f 75 74  n all three rout
36f80 69 6e 65 73 0a 2a 2a 20 62 65 68 61 76 65 20 61  ines.** behave a
36f90 73 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20  s no-ops..**.** 
36fa0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
36fb0 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 5d  e3_mutex_held()]
36fc0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6d 75   and [sqlite3_mu
36fd0 74 65 78 5f 6e 6f 74 68 65 6c 64 28 29 5d 2e 0a  tex_notheld()]..
36fe0 2a 2f 0a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  */.sqlite3_mutex
36ff0 20 2a 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   *sqlite3_mutex_
37000 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
37010 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 66   sqlite3_mutex_f
37020 72 65 65 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  ree(sqlite3_mute
37030 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  x*);.void sqlite
37040 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 73 71  3_mutex_enter(sq
37050 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a 69  lite3_mutex*);.i
37060 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  nt sqlite3_mutex
37070 5f 74 72 79 28 73 71 6c 69 74 65 33 5f 6d 75 74  _try(sqlite3_mut
37080 65 78 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ex*);.void sqlit
37090 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 73  e3_mutex_leave(s
370a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 2a 29 3b 0a  qlite3_mutex*);.
370b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
370c0 20 4d 75 74 65 78 20 4d 65 74 68 6f 64 73 20 4f   Mutex Methods O
370d0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  bject.**.** An i
370e0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
370f0 73 74 72 75 63 74 75 72 65 20 64 65 66 69 6e 65  structure define
37100 73 20 74 68 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  s the low-level 
37110 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 75 73 65 64  routines.** used
37120 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 6e 64   to allocate and
37130 20 75 73 65 20 6d 75 74 65 78 65 73 2e 0a 2a 2a   use mutexes..**
37140 0a 2a 2a 20 55 73 75 61 6c 6c 79 2c 20 74 68 65  .** Usually, the
37150 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 69   default mutex i
37160 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 70  mplementations p
37170 72 6f 76 69 64 65 64 20 62 79 20 53 51 4c 69 74  rovided by SQLit
37180 65 20 61 72 65 0a 2a 2a 20 73 75 66 66 69 63 69  e are.** suffici
37190 65 6e 74 2c 20 68 6f 77 65 76 65 72 20 74 68 65  ent, however the
371a0 20 75 73 65 72 20 68 61 73 20 74 68 65 20 6f 70   user has the op
371b0 74 69 6f 6e 20 6f 66 20 73 75 62 73 74 69 74 75  tion of substitu
371c0 74 69 6e 67 20 61 20 63 75 73 74 6f 6d 0a 2a 2a  ting a custom.**
371d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
371e0 66 6f 72 20 73 70 65 63 69 61 6c 69 7a 65 64 20  for specialized 
371f0 64 65 70 6c 6f 79 6d 65 6e 74 73 20 6f 72 20 73  deployments or s
37200 79 73 74 65 6d 73 20 66 6f 72 20 77 68 69 63 68  ystems for which
37210 20 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20   SQLite.** does 
37220 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 20 73 75  not provide a su
37230 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
37240 61 74 69 6f 6e 2e 20 49 6e 20 74 68 69 73 20 63  ation. In this c
37250 61 73 65 2c 20 74 68 65 20 75 73 65 72 0a 2a 2a  ase, the user.**
37260 20 63 72 65 61 74 65 73 20 61 6e 64 20 70 6f 70   creates and pop
37270 75 6c 61 74 65 73 20 61 6e 20 69 6e 73 74 61 6e  ulates an instan
37280 63 65 20 6f 66 20 74 68 69 73 20 73 74 72 75 63  ce of this struc
37290 74 75 72 65 20 74 6f 20 70 61 73 73 0a 2a 2a 20  ture to pass.** 
372a0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
372b0 67 28 29 20 61 6c 6f 6e 67 20 77 69 74 68 20 74  g() along with t
372c0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
372d0 47 5f 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e 2e  G_MUTEX] option.
372e0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  .** Additionally
372f0 2c 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  , an instance of
37300 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
37310 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 61  can be used as a
37320 6e 0a 2a 2a 20 6f 75 74 70 75 74 20 76 61 72 69  n.** output vari
37330 61 62 6c 65 20 77 68 65 6e 20 71 75 65 72 79 69  able when queryi
37340 6e 67 20 74 68 65 20 73 79 73 74 65 6d 20 66 6f  ng the system fo
37350 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 6d 75  r the current mu
37360 74 65 78 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  tex.** implement
37370 61 74 69 6f 6e 2c 20 75 73 69 6e 67 20 74 68 65  ation, using the
37380 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
37390 47 45 54 4d 55 54 45 58 5d 20 6f 70 74 69 6f 6e  GETMUTEX] option
373a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75  ..**.** ^The xMu
373b0 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 64  texInit method d
373c0 65 66 69 6e 65 64 20 62 79 20 74 68 69 73 20 73  efined by this s
373d0 74 72 75 63 74 75 72 65 20 69 73 20 69 6e 76 6f  tructure is invo
373e0 6b 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ked as.** part o
373f0 66 20 73 79 73 74 65 6d 20 69 6e 69 74 69 61 6c  f system initial
37400 69 7a 61 74 69 6f 6e 20 62 79 20 74 68 65 20 73  ization by the s
37410 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
37420 65 28 29 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  e() function..**
37430 20 5e 54 68 65 20 78 4d 75 74 65 78 49 6e 69 74   ^The xMutexInit
37440 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
37450 65 20 62 79 20 53 51 4c 69 74 65 20 65 78 61 63  e by SQLite exac
37460 74 6c 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  tly once for eac
37470 68 0a 2a 2a 20 65 66 66 65 63 74 69 76 65 20 63  h.** effective c
37480 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37490 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 2e 0a 2a  initialize()]..*
374a0 2a 0a 2a 2a 20 5e 54 68 65 20 78 4d 75 74 65 78  *.** ^The xMutex
374b0 45 6e 64 20 6d 65 74 68 6f 64 20 64 65 66 69 6e  End method defin
374c0 65 64 20 62 79 20 74 68 69 73 20 73 74 72 75 63  ed by this struc
374d0 74 75 72 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  ture is invoked 
374e0 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 73 79  as.** part of sy
374f0 73 74 65 6d 20 73 68 75 74 64 6f 77 6e 20 62 79  stem shutdown by
37500 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   the sqlite3_shu
37510 74 64 6f 77 6e 28 29 20 66 75 6e 63 74 69 6f 6e  tdown() function
37520 2e 20 54 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  . The.** impleme
37530 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 69 73 20  ntation of this 
37540 6d 65 74 68 6f 64 20 69 73 20 65 78 70 65 63 74  method is expect
37550 65 64 20 74 6f 20 72 65 6c 65 61 73 65 20 61 6c  ed to release al
37560 6c 20 6f 75 74 73 74 61 6e 64 69 6e 67 0a 2a 2a  l outstanding.**
37570 20 72 65 73 6f 75 72 63 65 73 20 6f 62 74 61 69   resources obtai
37580 6e 65 64 20 62 79 20 74 68 65 20 6d 75 74 65 78  ned by the mutex
37590 20 6d 65 74 68 6f 64 73 20 69 6d 70 6c 65 6d 65   methods impleme
375a0 6e 74 61 74 69 6f 6e 2c 20 65 73 70 65 63 69 61  ntation, especia
375b0 6c 6c 79 0a 2a 2a 20 74 68 6f 73 65 20 6f 62 74  lly.** those obt
375c0 61 69 6e 65 64 20 62 79 20 74 68 65 20 78 4d 75  ained by the xMu
375d0 74 65 78 49 6e 69 74 20 6d 65 74 68 6f 64 2e 20  texInit method. 
375e0 20 5e 54 68 65 20 78 4d 75 74 65 78 45 6e 64 28   ^The xMutexEnd(
375f0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
37600 73 20 69 6e 76 6f 6b 65 64 20 65 78 61 63 74 6c  s invoked exactl
37610 79 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  y once for each 
37620 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
37630 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
37640 0a 2a 2a 20 5e 28 54 68 65 20 72 65 6d 61 69 6e  .** ^(The remain
37650 69 6e 67 20 73 65 76 65 6e 20 6d 65 74 68 6f 64  ing seven method
37660 73 20 64 65 66 69 6e 65 64 20 62 79 20 74 68 69  s defined by thi
37670 73 20 73 74 72 75 63 74 75 72 65 20 28 78 4d 75  s structure (xMu
37680 74 65 78 41 6c 6c 6f 63 2c 0a 2a 2a 20 78 4d 75  texAlloc,.** xMu
37690 74 65 78 46 72 65 65 2c 20 78 4d 75 74 65 78 45  texFree, xMutexE
376a0 6e 74 65 72 2c 20 78 4d 75 74 65 78 54 72 79 2c  nter, xMutexTry,
376b0 20 78 4d 75 74 65 78 4c 65 61 76 65 2c 20 78 4d   xMutexLeave, xM
376c0 75 74 65 78 48 65 6c 64 20 61 6e 64 0a 2a 2a 20  utexHeld and.** 
376d0 78 4d 75 74 65 78 4e 6f 74 68 65 6c 64 29 20 69  xMutexNotheld) i
376e0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 66 6f 6c  mplement the fol
376f0 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
37700 73 20 28 72 65 73 70 65 63 74 69 76 65 6c 79 29  s (respectively)
37710 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
37720 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65 33    <li>  [sqlite3
37730 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 20  _mutex_alloc()] 
37740 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20  </li>.**   <li> 
37750 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
37760 66 72 65 65 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  free()] </li>.**
37770 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
37780 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 28 29 5d  3_mutex_enter()]
37790 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
377a0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
377b0 5f 74 72 79 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a  _try()] </li>.**
377c0 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74 65     <li>  [sqlite
377d0 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 28 29 5d  3_mutex_leave()]
377e0 20 3c 2f 6c 69 3e 0a 2a 2a 20 20 20 3c 6c 69 3e   </li>.**   <li>
377f0 20 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78    [sqlite3_mutex
37800 5f 68 65 6c 64 28 29 5d 20 3c 2f 6c 69 3e 0a 2a  _held()] </li>.*
37810 2a 20 20 20 3c 6c 69 3e 20 20 5b 73 71 6c 69 74  *   <li>  [sqlit
37820 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
37830 28 29 5d 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  ()] </li>.** </u
37840 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f  l>)^.**.** The o
37850 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 20 69  nly difference i
37860 73 20 74 68 61 74 20 74 68 65 20 70 75 62 6c 69  s that the publi
37870 63 20 73 71 6c 69 74 65 33 5f 58 58 58 20 66 75  c sqlite3_XXX fu
37880 6e 63 74 69 6f 6e 73 20 65 6e 75 6d 65 72 61 74  nctions enumerat
37890 65 64 0a 2a 2a 20 61 62 6f 76 65 20 73 69 6c 65  ed.** above sile
378a0 6e 74 6c 79 20 69 67 6e 6f 72 65 20 61 6e 79 20  ntly ignore any 
378b0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 74 68 61 74  invocations that
378c0 20 70 61 73 73 20 61 20 4e 55 4c 4c 20 70 6f 69   pass a NULL poi
378d0 6e 74 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  nter instead.** 
378e0 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78  of a valid mutex
378f0 20 68 61 6e 64 6c 65 2e 20 54 68 65 20 69 6d 70   handle. The imp
37900 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
37910 74 68 65 20 6d 65 74 68 6f 64 73 20 64 65 66 69  the methods defi
37920 6e 65 64 0a 2a 2a 20 62 79 20 74 68 69 73 20 73  ned.** by this s
37930 74 72 75 63 74 75 72 65 20 61 72 65 20 6e 6f 74  tructure are not
37940 20 72 65 71 75 69 72 65 64 20 74 6f 20 68 61 6e   required to han
37950 64 6c 65 20 74 68 69 73 20 63 61 73 65 2c 20 74  dle this case, t
37960 68 65 20 72 65 73 75 6c 74 73 0a 2a 2a 20 6f 66  he results.** of
37970 20 70 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   passing a NULL 
37980 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
37990 6f 66 20 61 20 76 61 6c 69 64 20 6d 75 74 65 78  of a valid mutex
379a0 20 68 61 6e 64 6c 65 20 61 72 65 20 75 6e 64 65   handle are unde
379b0 66 69 6e 65 64 0a 2a 2a 20 28 69 2e 65 2e 20 69  fined.** (i.e. i
379c0 74 20 69 73 20 61 63 63 65 70 74 61 62 6c 65 20  t is acceptable 
379d0 74 6f 20 70 72 6f 76 69 64 65 20 61 6e 20 69 6d  to provide an im
379e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
379f0 74 20 73 65 67 66 61 75 6c 74 73 20 69 66 0a 2a  t segfaults if.*
37a00 2a 20 69 74 20 69 73 20 70 61 73 73 65 64 20 61  * it is passed a
37a10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 29 2e 0a   NULL pointer)..
37a20 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 75 74 65 78  **.** The xMutex
37a30 49 6e 69 74 28 29 20 6d 65 74 68 6f 64 20 6d 75  Init() method mu
37a40 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
37a50 2e 20 20 5e 49 74 20 6d 75 73 74 20 62 65 20 68  .  ^It must be h
37a60 61 72 6d 6c 65 73 73 20 74 6f 0a 2a 2a 20 69 6e  armless to.** in
37a70 76 6f 6b 65 20 78 4d 75 74 65 78 49 6e 69 74 28  voke xMutexInit(
37a80 29 20 6d 75 74 69 70 6c 65 20 74 69 6d 65 73 20  ) mutiple times 
37a90 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
37aa0 70 72 6f 63 65 73 73 20 61 6e 64 20 77 69 74 68  process and with
37ab0 6f 75 74 0a 2a 2a 20 69 6e 74 65 72 76 65 6e 69  out.** interveni
37ac0 6e 67 20 63 61 6c 6c 73 20 74 6f 20 78 4d 75 74  ng calls to xMut
37ad0 65 78 45 6e 64 28 29 2e 20 20 53 65 63 6f 6e 64  exEnd().  Second
37ae0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
37af0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 78 4d 75 74  calls to.** xMut
37b00 65 78 49 6e 69 74 28 29 20 6d 75 73 74 20 62 65  exInit() must be
37b10 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 5e   no-ops..**.** ^
37b20 78 4d 75 74 65 78 49 6e 69 74 28 29 20 6d 75 73  xMutexInit() mus
37b30 74 20 6e 6f 74 20 75 73 65 20 53 51 4c 69 74 65  t not use SQLite
37b40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
37b50 6f 6e 20 28 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  on ([sqlite3_mal
37b60 6c 6f 63 28 29 5d 0a 2a 2a 20 61 6e 64 20 69 74  loc()].** and it
37b70 73 20 61 73 73 6f 63 69 61 74 65 73 29 2e 20 20  s associates).  
37b80 5e 53 69 6d 69 6c 61 72 6c 79 2c 20 78 4d 75 74  ^Similarly, xMut
37b90 65 78 41 6c 6c 6f 63 28 29 20 6d 75 73 74 20 6e  exAlloc() must n
37ba0 6f 74 20 75 73 65 20 53 51 4c 69 74 65 20 6d 65  ot use SQLite me
37bb0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
37bc0 6f 6e 20 66 6f 72 20 61 20 73 74 61 74 69 63 20  on for a static 
37bd0 6d 75 74 65 78 2e 20 20 5e 48 6f 77 65 76 65 72  mutex.  ^However
37be0 20 78 4d 75 74 65 78 41 6c 6c 6f 63 28 29 20 6d   xMutexAlloc() m
37bf0 61 79 20 75 73 65 20 53 51 4c 69 74 65 0a 2a 2a  ay use SQLite.**
37c00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
37c10 6f 6e 20 66 6f 72 20 61 20 66 61 73 74 20 6f 72  on for a fast or
37c20 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
37c30 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
37c40 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
37c50 78 4d 75 74 65 78 45 6e 64 28 29 20 6d 65 74 68  xMutexEnd() meth
37c60 6f 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  od when [sqlite3
37c70 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 69 73 0a  _shutdown()] is.
37c80 2a 2a 20 63 61 6c 6c 65 64 2c 20 62 75 74 20 6f  ** called, but o
37c90 6e 6c 79 20 69 66 20 74 68 65 20 70 72 69 6f 72  nly if the prior
37ca0 20 63 61 6c 6c 20 74 6f 20 78 4d 75 74 65 78 49   call to xMutexI
37cb0 6e 69 74 20 72 65 74 75 72 6e 65 64 20 53 51 4c  nit returned SQL
37cc0 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 49 66 20 78 4d  ITE_OK..** If xM
37cd0 75 74 65 78 49 6e 69 74 20 66 61 69 6c 73 20 69  utexInit fails i
37ce0 6e 20 61 6e 79 20 77 61 79 2c 20 69 74 20 69 73  n any way, it is
37cf0 20 65 78 70 65 63 74 65 64 20 74 6f 20 63 6c 65   expected to cle
37d00 61 6e 20 75 70 20 61 66 74 65 72 20 69 74 73 65  an up after itse
37d10 6c 66 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 72  lf.** prior to r
37d20 65 74 75 72 6e 69 6e 67 2e 0a 2a 2f 0a 74 79 70  eturning..*/.typ
37d30 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
37d40 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
37d50 73 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  s sqlite3_mutex_
37d60 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
37d70 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
37d80 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 28 2a  thods {.  int (*
37d90 78 4d 75 74 65 78 49 6e 69 74 29 28 76 6f 69 64  xMutexInit)(void
37da0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65  );.  int (*xMute
37db0 78 45 6e 64 29 28 76 6f 69 64 29 3b 0a 20 20 73  xEnd)(void);.  s
37dc0 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 28 2a  qlite3_mutex *(*
37dd0 78 4d 75 74 65 78 41 6c 6c 6f 63 29 28 69 6e 74  xMutexAlloc)(int
37de0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 4d 75 74  );.  void (*xMut
37df0 65 78 46 72 65 65 29 28 73 71 6c 69 74 65 33 5f  exFree)(sqlite3_
37e00 6d 75 74 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64  mutex *);.  void
37e10 20 28 2a 78 4d 75 74 65 78 45 6e 74 65 72 29 28   (*xMutexEnter)(
37e20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 2a 29  sqlite3_mutex *)
37e30 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75 74 65 78  ;.  int (*xMutex
37e40 54 72 79 29 28 73 71 6c 69 74 65 33 5f 6d 75 74  Try)(sqlite3_mut
37e50 65 78 20 2a 29 3b 0a 20 20 76 6f 69 64 20 28 2a  ex *);.  void (*
37e60 78 4d 75 74 65 78 4c 65 61 76 65 29 28 73 71 6c  xMutexLeave)(sql
37e70 69 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 20  ite3_mutex *);. 
37e80 20 69 6e 74 20 28 2a 78 4d 75 74 65 78 48 65 6c   int (*xMutexHel
37e90 64 29 28 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  d)(sqlite3_mutex
37ea0 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4d 75   *);.  int (*xMu
37eb0 74 65 78 4e 6f 74 68 65 6c 64 29 28 73 71 6c 69  texNotheld)(sqli
37ec0 74 65 33 5f 6d 75 74 65 78 20 2a 29 3b 0a 7d 3b  te3_mutex *);.};
37ed0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37ee0 3a 20 4d 75 74 65 78 20 56 65 72 69 66 69 63 61  : Mutex Verifica
37ef0 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
37f00 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
37f10 6d 75 74 65 78 5f 68 65 6c 64 28 29 20 61 6e 64  mutex_held() and
37f20 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e   sqlite3_mutex_n
37f30 6f 74 68 65 6c 64 28 29 20 72 6f 75 74 69 6e 65  otheld() routine
37f40 73 0a 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65  s.** are intende
37f50 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
37f60 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
37f70 65 6e 74 73 2e 20 20 5e 54 68 65 20 53 51 4c 69  ents.  ^The SQLi
37f80 74 65 20 63 6f 72 65 0a 2a 2a 20 6e 65 76 65 72  te core.** never
37f90 20 75 73 65 73 20 74 68 65 73 65 20 72 6f 75 74   uses these rout
37fa0 69 6e 65 73 20 65 78 63 65 70 74 20 69 6e 73 69  ines except insi
37fb0 64 65 20 61 6e 20 61 73 73 65 72 74 28 29 20 61  de an assert() a
37fc0 6e 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  nd applications.
37fd0 2a 2a 20 61 72 65 20 61 64 76 69 73 65 64 20 74  ** are advised t
37fe0 6f 20 66 6f 6c 6c 6f 77 20 74 68 65 20 6c 65 61  o follow the lea
37ff0 64 20 6f 66 20 74 68 65 20 63 6f 72 65 2e 20 20  d of the core.  
38000 5e 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65  ^The SQLite core
38010 20 6f 6e 6c 79 0a 2a 2a 20 70 72 6f 76 69 64 65   only.** provide
38020 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
38030 73 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  s for these rout
38040 69 6e 65 73 20 77 68 65 6e 20 69 74 20 69 73 20  ines when it is 
38050 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68  compiled.** with
38060 20 74 68 65 20 53 51 4c 49 54 45 5f 44 45 42 55   the SQLITE_DEBU
38070 47 20 66 6c 61 67 2e 20 20 5e 45 78 74 65 72 6e  G flag.  ^Extern
38080 61 6c 20 6d 75 74 65 78 20 69 6d 70 6c 65 6d 65  al mutex impleme
38090 6e 74 61 74 69 6f 6e 73 0a 2a 2a 20 61 72 65 20  ntations.** are 
380a0 6f 6e 6c 79 20 72 65 71 75 69 72 65 64 20 74 6f  only required to
380b0 20 70 72 6f 76 69 64 65 20 74 68 65 73 65 20 72   provide these r
380c0 6f 75 74 69 6e 65 73 20 69 66 20 53 51 4c 49 54  outines if SQLIT
380d0 45 5f 44 45 42 55 47 20 69 73 0a 2a 2a 20 64 65  E_DEBUG is.** de
380e0 66 69 6e 65 64 20 61 6e 64 20 69 66 20 4e 44 45  fined and if NDE
380f0 42 55 47 20 69 73 20 6e 6f 74 20 64 65 66 69 6e  BUG is not defin
38100 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
38110 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
38120 20 72 65 74 75 72 6e 20 74 72 75 65 20 69 66 20   return true if 
38130 74 68 65 20 6d 75 74 65 78 20 69 6e 20 74 68 65  the mutex in the
38140 69 72 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 69  ir argument.** i
38150 73 20 68 65 6c 64 20 6f 72 20 6e 6f 74 20 68 65  s held or not he
38160 6c 64 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  ld, respectively
38170 2c 20 62 79 20 74 68 65 20 63 61 6c 6c 69 6e 67  , by the calling
38180 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 5e   thread..**.** ^
38190 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  The implementati
381a0 6f 6e 20 69 73 20 6e 6f 74 20 72 65 71 75 69 72  on is not requir
381b0 65 64 20 74 6f 20 70 72 6f 76 69 64 65 64 20 76  ed to provided v
381c0 65 72 73 69 6f 6e 73 20 6f 66 20 74 68 65 73 65  ersions of these
381d0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
381e0 74 20 61 63 74 75 61 6c 6c 79 20 77 6f 72 6b 2e  t actually work.
381f0 20 49 66 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   If the implemen
38200 74 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  tation does not 
38210 70 72 6f 76 69 64 65 20 77 6f 72 6b 69 6e 67 0a  provide working.
38220 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  ** versions of t
38230 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 69  hese routines, i
38240 74 20 73 68 6f 75 6c 64 20 61 74 20 6c 65 61 73  t should at leas
38250 74 20 70 72 6f 76 69 64 65 20 73 74 75 62 73 20  t provide stubs 
38260 74 68 61 74 20 61 6c 77 61 79 73 0a 2a 2a 20 72  that always.** r
38270 65 74 75 72 6e 20 74 72 75 65 20 73 6f 20 74 68  eturn true so th
38280 61 74 20 6f 6e 65 20 64 6f 65 73 20 6e 6f 74 20  at one does not 
38290 67 65 74 20 73 70 75 72 69 6f 75 73 20 61 73 73  get spurious ass
382a0 65 72 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 2e  ertion failures.
382b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  .**.** ^If the a
382c0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
382d0 65 33 5f 6d 75 74 65 78 5f 68 65 6c 64 28 29 20  e3_mutex_held() 
382e0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
382f0 72 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 6f  r then.** the ro
38300 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 72 65 74  utine should ret
38310 75 72 6e 20 31 2e 20 20 20 54 68 69 73 20 73 65  urn 1.   This se
38320 65 6d 73 20 63 6f 75 6e 74 65 72 2d 69 6e 74 75  ems counter-intu
38330 69 74 69 76 65 20 73 69 6e 63 65 0a 2a 2a 20 63  itive since.** c
38340 6c 65 61 72 6c 79 20 74 68 65 20 6d 75 74 65 78  learly the mutex
38350 20 63 61 6e 6e 6f 74 20 62 65 20 68 65 6c 64 20   cannot be held 
38360 69 66 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  if it does not e
38370 78 69 73 74 2e 20 20 42 75 74 20 74 68 65 0a 2a  xist.  But the.*
38380 2a 20 74 68 65 20 72 65 61 73 6f 6e 20 74 68 65  * the reason the
38390 20 6d 75 74 65 78 20 64 6f 65 73 20 6e 6f 74 20   mutex does not 
383a0 65 78 69 73 74 20 69 73 20 62 65 63 61 75 73 65  exist is because
383b0 20 74 68 65 20 62 75 69 6c 64 20 69 73 20 6e 6f   the build is no
383c0 74 0a 2a 2a 20 75 73 69 6e 67 20 6d 75 74 65 78  t.** using mutex
383d0 65 73 2e 20 20 41 6e 64 20 77 65 20 64 6f 20 6e  es.  And we do n
383e0 6f 74 20 77 61 6e 74 20 74 68 65 20 61 73 73 65  ot want the asse
383f0 72 74 28 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rt() containing 
38400 74 68 65 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  the.** call to s
38410 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 68 65 6c  qlite3_mutex_hel
38420 64 28 29 20 74 6f 20 66 61 69 6c 2c 20 73 6f 20  d() to fail, so 
38430 61 20 6e 6f 6e 2d 7a 65 72 6f 20 72 65 74 75 72  a non-zero retur
38440 6e 20 69 73 0a 2a 2a 20 74 68 65 20 61 70 70 72  n is.** the appr
38450 6f 70 72 69 61 74 65 20 74 68 69 6e 67 20 74 6f  opriate thing to
38460 20 64 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74   do.  ^The sqlit
38470 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68 65 6c 64  e3_mutex_notheld
38480 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
38490 73 68 6f 75 6c 64 20 61 6c 73 6f 20 72 65 74 75  should also retu
384a0 72 6e 20 31 20 77 68 65 6e 20 67 69 76 65 6e 20  rn 1 when given 
384b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
384c0 2a 2f 0a 23 69 66 6e 64 65 66 20 4e 44 45 42 55  */.#ifndef NDEBU
384d0 47 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 75  G.int sqlite3_mu
384e0 74 65 78 5f 68 65 6c 64 28 73 71 6c 69 74 65 33  tex_held(sqlite3
384f0 5f 6d 75 74 65 78 2a 29 3b 0a 69 6e 74 20 73 71  _mutex*);.int sq
38500 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6e 6f 74 68  lite3_mutex_noth
38510 65 6c 64 28 73 71 6c 69 74 65 33 5f 6d 75 74 65  eld(sqlite3_mute
38520 78 2a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  x*);.#endif../*.
38530 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
38540 65 78 20 54 79 70 65 73 0a 2a 2a 0a 2a 2a 20 54  ex Types.**.** T
38550 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
38560 78 5f 61 6c 6c 6f 63 28 29 5d 20 69 6e 74 65 72  x_alloc()] inter
38570 66 61 63 65 20 74 61 6b 65 73 20 61 20 73 69 6e  face takes a sin
38580 67 6c 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  gle argument.** 
38590 77 68 69 63 68 20 69 73 20 6f 6e 65 20 6f 66 20  which is one of 
385a0 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  these integer co
385b0 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  nstants..**.** T
385c0 68 65 20 73 65 74 20 6f 66 20 73 74 61 74 69 63  he set of static
385d0 20 6d 75 74 65 78 65 73 20 6d 61 79 20 63 68 61   mutexes may cha
385e0 6e 67 65 20 66 72 6f 6d 20 6f 6e 65 20 53 51 4c  nge from one SQL
385f0 69 74 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74  ite release to t
38600 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
38610 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6f  lications that o
38620 76 65 72 72 69 64 65 20 74 68 65 20 62 75 69 6c  verride the buil
38630 74 2d 69 6e 20 6d 75 74 65 78 20 6c 6f 67 69 63  t-in mutex logic
38640 20 6d 75 73 74 20 62 65 0a 2a 2a 20 70 72 65 70   must be.** prep
38650 61 72 65 64 20 74 6f 20 61 63 63 6f 6d 6d 6f 64  ared to accommod
38660 61 74 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  ate additional s
38670 74 61 74 69 63 20 6d 75 74 65 78 65 73 2e 0a 2a  tatic mutexes..*
38680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
38690 5f 4d 55 54 45 58 5f 46 41 53 54 20 20 20 20 20  _MUTEX_FAST     
386a0 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
386b0 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 52  e SQLITE_MUTEX_R
386c0 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
386d0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
386e0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
386f0 53 54 45 52 20 20 20 20 32 0a 23 64 65 66 69 6e  STER    2.#defin
38700 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
38710 54 41 54 49 43 5f 4d 45 4d 20 20 20 20 20 20 20  TATIC_MEM       
38720 33 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 61  3  /* sqlite3_ma
38730 6c 6c 6f 63 28 29 20 2a 2f 0a 23 64 65 66 69 6e  lloc() */.#defin
38740 65 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53  e SQLITE_MUTEX_S
38750 54 41 54 49 43 5f 4d 45 4d 32 20 20 20 20 20 20  TATIC_MEM2      
38760 34 20 20 2f 2a 20 4e 4f 54 20 55 53 45 44 20 2a  4  /* NOT USED *
38770 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
38780 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4f 50  _MUTEX_STATIC_OP
38790 45 4e 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71  EN      4  /* sq
387a0 6c 69 74 65 33 42 74 72 65 65 4f 70 65 6e 28 29  lite3BtreeOpen()
387b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
387c0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
387d0 50 52 4e 47 20 20 20 20 20 20 35 20 20 2f 2a 20  PRNG      5  /* 
387e0 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 28 29  sqlite3_random()
387f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
38800 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
38810 4c 52 55 20 20 20 20 20 20 20 36 20 20 2f 2a 20  LRU       6  /* 
38820 6c 72 75 20 70 61 67 65 20 6c 69 73 74 20 2a 2f  lru page list */
38830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
38840 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4c 52 55  MUTEX_STATIC_LRU
38850 32 20 20 20 20 20 20 37 20 20 2f 2a 20 6c 72 75  2      7  /* lru
38860 20 70 61 67 65 20 6c 69 73 74 20 2a 2f 0a 0a 2f   page list */../
38870 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
38880 65 74 72 69 65 76 65 20 74 68 65 20 6d 75 74 65  etrieve the mute
38890 78 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65  x for a database
388a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   connection.**.*
388b0 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
388c0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
388d0 74 65 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ter the [sqlite3
388e0 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 20 74  _mutex] object t
388f0 68 61 74 20 0a 2a 2a 20 7