/ Hex Artifact Content
Login

Artifact 0c3ab42eef59ee80c564be76c700b542ff530758:


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 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
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: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 0a 2a   result codes].*
3e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3e50: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
3e60: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
3e70: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
3e80: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
3e90: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
3ea0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
3eb0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
3ec0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
3ed0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
3ef0: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
3f00: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
3f10: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
3f20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3f30: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
3f40: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
3f50: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
3f60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f70: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
3f80: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
3f90: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
3fa0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
3fb0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
3fc0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
3fd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
3fe0: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
3ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4000: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4010: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4020: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4030: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4040: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4050: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4060: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
4080: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
4090: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
40a0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
40b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
40c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
40d0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
40e0: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
40f0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4100: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4110: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4120: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4130: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4140: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4150: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4160: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4170: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
4180: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
4190: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
41a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
41b0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
41c0: 2a 20 4e 4f 54 20 55 53 45 44 2e 20 54 61 62 6c  * NOT USED. Tabl
41d0: 65 20 6f 72 20 72 65 63 6f 72 64 20 6e 6f 74 20  e or record not 
41e0: 66 6f 75 6e 64 20 2a 2f 0a 23 64 65 66 69 6e 65  found */.#define
41f0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20   SQLITE_FULL    
4200: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65      13   /* Inse
4210: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63  rtion failed bec
4220: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73  ause database is
4230: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65   full */.#define
4240: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
4250: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62      14   /* Unab
4260: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  le to open the d
4270: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4290: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20  ROTOCOL    15   
42a0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b  /* Database lock
42b0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20   protocol error 
42c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
42d0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36  E_EMPTY       16
42e0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69     /* Database i
42f0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69  s empty */.#defi
4300: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  ne SQLITE_SCHEMA
4310: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68        17   /* Th
4320: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
4330: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65  a changed */.#de
4340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42  fine SQLITE_TOOB
4350: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20  IG      18   /* 
4360: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65  String or BLOB e
4370: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69  xceeds size limi
4380: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20  ITE_CONSTRAINT  
43a0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75  19   /* Abort du
43b0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20  e to constraint 
43c0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65  violation */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d  fine SQLITE_MISM
43e0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20  ATCH    20   /* 
43f0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74  Data type mismat
4400: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ch */.#define SQ
4410: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20  LITE_MISUSE     
4420: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79   21   /* Library
4430: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c   used incorrectl
4440: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4450: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20  ITE_NOLFS       
4460: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20  22   /* Uses OS 
4470: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70  features not sup
4480: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a  ported on host *
4490: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44a0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20  _AUTH        23 
44b0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69    /* Authorizati
44c0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65  on denied */.#de
44d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d  fine SQLITE_FORM
44e0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20  AT      24   /* 
44f0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61  Auxiliary databa
4500: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20  se format error 
4510: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4520: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35  E_RANGE       25
4530: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65     /* 2nd parame
4540: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
4550: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65  ind out of range
4560: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4570: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32  TE_NOTADB      2
4580: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e  6   /* File open
4590: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61  ed that is not a
45a0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
45b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45c0: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30  _ROW         100
45d0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
45e0: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20  p() has another 
45f0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65  row ready */.#de
4600: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45  fine SQLITE_DONE
4610: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20          101  /* 
4620: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4630: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
4640: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d  uting */./* end-
4650: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
4660: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
4670: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  F: Extended Resu
4680: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4690: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20  ORDS: {extended 
46a0: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74  error code} {ext
46b0: 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
46c0: 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
46d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
46e0: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
46f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a   result codes}.*
4700: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
4710: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
4720: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
4730: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
4740: 65 20 6f 66 20 32 36 20 69 6e 74 65 67 65 72 0a  e of 26 integer.
4750: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20  ** [SQLITE_OK | 
4760: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
4770: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
4780: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
4790: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
47a0: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
47b0: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
47c0: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
47d0: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
47e0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
47f0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
4800: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
4810: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
4820: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
4830: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
4840: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
4850: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
4860: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
4870: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
4880: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
4890: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
48a0: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
48b0: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
48c0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
48d0: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 20 65  ut errors. The e
48e0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
48f0: 6f 64 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  odes are enabled
4900: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4910: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4920: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4930: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4940: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4950: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4960: 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  ] API..**.** Som
4970: 65 20 6f 66 20 74 68 65 20 61 76 61 69 6c 61 62  e of the availab
4980: 6c 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  le extended resu
4990: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 6c 69 73  lt codes are lis
49a0: 74 65 64 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65  ted here..** One
49b0: 20 6d 61 79 20 65 78 70 65 63 74 20 74 68 65 20   may expect the 
49c0: 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 65 6e 64  number of extend
49d0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49e0: 77 69 6c 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a  will be expand.*
49f0: 2a 20 6f 76 65 72 20 74 69 6d 65 2e 20 20 53 6f  * over time.  So
4a00: 66 74 77 61 72 65 20 74 68 61 74 20 75 73 65 73  ftware that uses
4a10: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4a20: 20 63 6f 64 65 73 20 73 68 6f 75 6c 64 20 65 78   codes should ex
4a30: 70 65 63 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e  pect.** to see n
4a40: 65 77 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ew result codes 
4a50: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
4a60: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
4a70: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  .** The SQLITE_O
4a80: 4b 20 72 65 73 75 6c 74 20 63 6f 64 65 20 77 69  K result code wi
4a90: 6c 6c 20 6e 65 76 65 72 20 62 65 20 65 78 74 65  ll never be exte
4aa0: 6e 64 65 64 2e 20 20 49 74 20 77 69 6c 6c 20 61  nded.  It will a
4ab0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 65 78 61 63  lways.** be exac
4ac0: 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65  tly zero..*/.#de
4ad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ae0: 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  R_READ          
4af0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4b00: 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  R | (1<<8)).#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4b20: 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20  _SHORT_READ     
4b30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4b40: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
4b50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4b60: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
4b70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4b80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
4b90: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
4ba0: 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20  SYNC            
4bb0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4bc0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
4bd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4be0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
4bf0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4c00: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
4c10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55  SQLITE_IOERR_TRU
4c20: 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28  NCATE          (
4c30: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4c40: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
4c50: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41  QLITE_IOERR_FSTA
4c60: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  T             (S
4c70: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37  QLITE_IOERR | (7
4c80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c90: 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43  LITE_IOERR_UNLOC
4ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  K            (SQ
4cb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c  LITE_IOERR | (8<
4cc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4cd0: 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b  ITE_IOERR_RDLOCK
4ce0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4cf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c  ITE_IOERR | (9<<
4d00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d10: 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20  TE_IOERR_DELETE 
4d20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c  TE_IOERR | (10<<
4d40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d50: 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
4d60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4d70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c  TE_IOERR | (11<<
4d80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4d90: 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20  TE_IOERR_NOMEM  
4da0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4db0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c  TE_IOERR | (12<<
4dc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4dd0: 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20  TE_IOERR_ACCESS 
4de0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4df0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c  TE_IOERR | (13<<
4e00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e10: 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45  TE_IOERR_CHECKRE
4e20: 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49  SERVEDLOCK (SQLI
4e30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c  TE_IOERR | (14<<
4e40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e50: 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20  TE_IOERR_LOCK   
4e60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4e70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c  TE_IOERR | (15<<
4e80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e90: 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20  TE_IOERR_CLOSE  
4ea0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4eb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c  TE_IOERR | (16<<
4ec0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ed0: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f  TE_IOERR_DIR_CLO
4ee0: 53 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  SE         (SQLI
4ef0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c  TE_IOERR | (17<<
4f00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f10: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e  TE_IOERR_SHMOPEN
4f20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c  TE_IOERR | (18<<
4f40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f50: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45  TE_IOERR_SHMSIZE
4f60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4f70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c  TE_IOERR | (19<<
4f80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4f90: 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b  TE_IOERR_SHMLOCK
4fa0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4fb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c  TE_IOERR | (20<<
4fc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4fd0: 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44  TE_LOCKED_SHARED
4fe0: 43 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49  CACHE      (SQLI
4ff0: 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c  TE_LOCKED |  (1<
5000: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5010: 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52  ITE_BUSY_RECOVER
5020: 59 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  Y           (SQL
5030: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31  ITE_BUSY   |  (1
5040: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5050: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5060: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5070: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5080: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5090: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
50a0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
50b0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
50c0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
50d0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
50e0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
50f0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5100: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5110: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5120: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5130: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5140: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
5150: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
5160: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
5170: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5180: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
5190: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
51a0: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
51b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
51d0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
51e0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
51f0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
5200: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5210: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5220: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
5230: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5240: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
5250: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5260: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5270: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
5280: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
5290: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
52a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
52c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
52d0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
52e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
52f0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
5300: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
5310: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
5320: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5330: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
5340: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5350: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
5360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5370: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
5380: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5390: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
53a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53b0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
53c0: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
53d0: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
53e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
53f0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
5400: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
5410: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
5420: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5430: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
5440: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
5450: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5470: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
5480: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
5490: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54b0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
54c0: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
54d0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
54e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
54f0: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
5500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
5510: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5520: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5530: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5540: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
5550: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
5560: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5570: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5590: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
55a0: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
55b0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
55c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
55d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
55e0: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
55f0: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
5600: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
5610: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5620: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
5630: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
5640: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
5650: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
5660: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
5670: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
5680: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
5690: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
56a0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
56b0: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
56c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
56d0: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
56e0: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
56f0: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
5700: 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62  f the these.** b
5710: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
5720: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
5730: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
5740: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
5750: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
5760: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
5790: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
57a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
57b0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
57c0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
57d0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
57e0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
57f0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5800: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
5810: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
5820: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
5830: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
5840: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
5850: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
5860: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
5870: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
5880: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
5890: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
58a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
58b0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
58c0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
58d0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
58e0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
58f0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
5900: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
5910: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
5920: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
5930: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
5940: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
5950: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
5960: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
5970: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
5980: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
5990: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
59a0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
59b0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
59c0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
59d0: 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ()..*/.#define S
59e0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
59f0: 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  IC              
5a00: 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64     0x00000001.#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a20: 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20  AP_ATOMIC512    
5a30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5a40: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
5a50: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5a60: 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  1K              
5a70: 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66   0x00000004.#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5a90: 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20  _ATOMIC2K       
5aa0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ab0: 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  08.#define SQLIT
5ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
5ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5ae0: 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e  x00000010.#defin
5af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b00: 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20  TOMIC8K         
5b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20  IOCAP_ATOMIC16K 
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5b50: 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20  0000040.#define 
5b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5b70: 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20  MIC32K          
5b80: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23      0x00000080.#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5ba0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20  CAP_ATOMIC64K   
5bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5bc0: 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00100.#define SQ
5bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
5be0: 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20  APPEND          
5bf0: 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65    0x00000200.#de
5c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c10: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20  P_SEQUENTIAL    
5c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c30: 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  400.#define SQLI
5c40: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54  TE_IOCAP_UNDELET
5c50: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20  ABLE_WHEN_OPEN  
5c60: 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a  0x00000800../*.*
5c70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
5c80: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
5c90: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
5ca0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
5cb0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
5cc0: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
5cd0: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
5ce0: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
5cf0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
5d00: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
5d10: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
5d20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
5d30: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
5d40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
5d50: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
5d60: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
5d70: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
5d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
5d90: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
5da0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
5db0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
5dc0: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
5dd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
5de0: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
5df0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
5e00: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
5e10: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
5e20: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
5e30: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
5e40: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
5e50: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5e60: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
5e70: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
5e80: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
5e90: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
5ea0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
5eb0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
5ec0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
5ed0: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
5ee0: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
5ef0: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
5f00: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
5f10: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
5f20: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
5f30: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
5f40: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
5f50: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
5f60: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
5f70: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
5f80: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
5f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
5fa0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
5fb0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
5fc0: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
5fd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
5fe0: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
5ff0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
6000: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
6010: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
6020: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
6030: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2f 0a   of fsync()..*/.
6040: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6050: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20  YNC_NORMAL      
6060: 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e    0x00002.#defin
6070: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  e SQLITE_SYNC_FU
6080: 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30  LL          0x00
6090: 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  003.#define SQLI
60a0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
60b0: 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f        0x00010../
60c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
60d0: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e  S Interface Open
60e0: 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a   File Handle.**.
60f0: 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66  ** An [sqlite3_f
6100: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72  ile] object repr
6110: 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66  esents an open f
6120: 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b  ile in the .** [
6130: 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53  sqlite3_vfs | OS
6140: 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
6150: 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f  ].  Individual O
6160: 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  S interface.** i
6170: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77  mplementations w
6180: 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73  ill.** want to s
6190: 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a  ubclass this obj
61a0: 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67  ect by appending
61b0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
61c0: 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20  ds.** for their 
61d0: 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d  own use.  The pM
61e0: 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20  ethods entry is 
61f0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
6200: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ** [sqlite3_io_m
6210: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74  ethods] object t
6220: 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68  hat defines meth
6230: 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69  ods for performi
6240: 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74  ng.** I/O operat
6250: 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e  ions on the open
6260: 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65   file..*/.typede
6270: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
6280: 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69  _file sqlite3_fi
6290: 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  le;.struct sqlit
62a0: 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73  e3_file {.  cons
62b0: 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  t struct sqlite3
62c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65  _io_methods *pMe
62d0: 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f  thods;  /* Metho
62e0: 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66  ds for an open f
62f0: 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ile */.};../*.**
6300: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6310: 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72  terface File Vir
6320: 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a  tual Methods Obj
6330: 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  ect.**.** Every 
6340: 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74  file opened by t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
6360: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 70 6f   xOpen method po
6370: 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73  pulates an.** [s
6380: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
6390: 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f  ect (or, more co
63a0: 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61  mmonly, a subcla
63b0: 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  ss of the.** [sq
63c0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
63d0: 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  ct) with a point
63e0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
63f0: 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
6400: 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
6410: 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74   defines the met
6420: 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72  hods used to per
6430: 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65  form various ope
6440: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e  rations.** again
6450: 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  st the open file
6460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
6470: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
6480: 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  e] object..**.**
6490: 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   If the xOpen me
64a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
64b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
64c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
64d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
64e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
64f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6500: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6510: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6520: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 78  ed even if the x
6530: 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20 74 68  Open reported th
6540: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6550: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6560: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6570: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6580: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 78 4f  wing a failed xO
6590: 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  pen.** is for th
65a0: 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74 20 74  e xOpen to set t
65b0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
65c0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
65d0: 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   to NULL..**.** 
65e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
65f0: 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20  nt to xSync may 
6600: 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  be one of [SQLIT
6610: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f  E_SYNC_NORMAL] o
6620: 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e  r.** [SQLITE_SYN
6630: 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69  C_FULL].  The fi
6640: 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68  rst choice is th
6650: 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29  e normal fsync()
6660: 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
6670: 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20  choice is a Mac 
6680: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73  OS X style fulls
6690: 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ync.  The [SQLIT
66a0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d  E_SYNC_DATAONLY]
66b0: 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20  .** flag may be 
66c0: 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63  ORed in to indic
66d0: 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68  ate that only th
66e0: 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69  e data of the fi
66f0: 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74  le.** and not it
6700: 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f  s inode needs to
6710: 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a   be synced..**.*
6720: 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61  * The integer va
6730: 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20  lues to xLock() 
6740: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72  and xUnlock() ar
6750: 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e  e one of.** <ul>
6760: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6770: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20  _LOCK_NONE],.** 
6780: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6790: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c  K_SHARED],.** <l
67a0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67b0: 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c  RESERVED],.** <l
67c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
67d0: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20  PENDING], or.** 
67e0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
67f0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a  K_EXCLUSIVE]..**
6800: 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28   </ul>.** xLock(
6810: 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20  ) increases the 
6820: 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20  lock. xUnlock() 
6830: 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  decreases the lo
6840: 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63  ck..** The xChec
6850: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20  kReservedLock() 
6860: 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68  method checks wh
6870: 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61  ether any databa
6880: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a  se connection,.*
6890: 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73  * either in this
68a0: 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73   process or in s
68b0: 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73  ome other proces
68c0: 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  s, is holding a 
68d0: 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e  RESERVED,.** PEN
68e0: 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49  DING, or EXCLUSI
68f0: 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66  VE lock on the f
6900: 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73  ile.  It returns
6910: 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68   true.** if such
6920: 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61   a lock exists a
6930: 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69  nd false otherwi
6940: 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  se..**.** The xF
6950: 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74  ileControl() met
6960: 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63  hod is a generic
6970: 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
6980: 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a  allows custom.**
6990: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
69a0: 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79  ions to directly
69b0: 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e   control an open
69c0: 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a   file using the.
69d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
69e0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65  _control()] inte
69f0: 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f  rface.  The seco
6a00: 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74  nd "op" argument
6a10: 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65   is an.** intege
6a20: 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74  r opcode.  The t
6a30: 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
6a40: 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74   a generic point
6a50: 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a  er intended to.*
6a60: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  * point to a str
6a70: 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20  ucture that may 
6a80: 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74  contain argument
6a90: 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68  s or space in wh
6aa0: 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20  ich to.** write 
6ab0: 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20  return values.  
6ac0: 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66  Potential uses f
6ad0: 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  or xFileControl(
6ae0: 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75  ) might be.** fu
6af0: 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c  nctions to enabl
6b00: 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73  e blocking locks
6b10: 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20   with timeouts, 
6b20: 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  to change the.**
6b30: 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67   locking strateg
6b40: 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74  y (for example t
6b50: 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c  o use dot-file l
6b60: 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72  ocks), to inquir
6b70: 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73  e.** about the s
6b80: 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c  tatus of a lock,
6b90: 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61   or to break sta
6ba0: 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53  le locks.  The S
6bb0: 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65  QLite.** core re
6bc0: 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64  serves all opcod
6bd0: 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  es less than 100
6be0: 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65   for its own use
6bf0: 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46  ..** A [SQLITE_F
6c00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c  CNTL_LOCKSTATE |
6c10: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
6c20: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
6c30: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
6c40: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
6c50: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
6c60: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
6c70: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
6c80: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
6c90: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
6ca0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
6cb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
6cc0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
6cd0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
6ce0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
6cf0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
6d00: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
6d10: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
6d20: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
6d30: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
6d40: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
6d50: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
6d60: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
6d70: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
6d80: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
6d90: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
6da0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
6db0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
6dc0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
6dd0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
6de0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
6df0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6e00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6e10: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
6e20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
6e30: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
6e40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e50: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
6e60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e70: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
6e80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6e90: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
6ea0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6eb0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
6ec0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
6ed0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
6ee0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
6ef0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
6f00: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
6f10: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
6f20: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
6f30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
6f40: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6f50: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6f60: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
6f70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6f80: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6f90: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6fa0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6fb0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6fc0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6fd0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6fe0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6ff0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
7000: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
7010: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
7020: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
7030: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
7040: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
7050: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
7060: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
7070: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
7080: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7090: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
70a0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
70b0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
70c0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
70d0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
70e0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
70f0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
7100: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
7110: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
7120: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
7130: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
7140: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
7150: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
7160: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
7170: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
7180: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
7190: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
71a0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
71b0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
71c0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
71d0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
71e0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
71f0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
7200: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
7210: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
7220: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
7230: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
7240: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
7250: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
7260: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
7270: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
7280: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
7290: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
72a0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
72b0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
72c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
72d0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
72e0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
72f0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
7300: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7310: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
7320: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
7330: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
7340: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
7350: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
7360: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
7370: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
7380: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
7390: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
73a0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
73b0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
73c0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
73d0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
73e0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
73f0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
7400: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
7410: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
7420: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
7430: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
7440: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
7450: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
7460: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
7470: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
7480: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7490: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
74a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
74b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
74c0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
74d0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
74e0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
74f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7500: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
7510: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
7520: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
7530: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
7540: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7550: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
7560: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
7570: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7580: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7590: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
75a0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
75b0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
75c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
75d0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
75e0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
75f0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
7600: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
7610: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
7620: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
7630: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
7640: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
7650: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7660: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
7670: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
7680: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
7690: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
76a0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
76b0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
76c0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c  .  /* Additional
76d0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20   methods may be 
76e0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
76f0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a  releases */.};..
7700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
7710: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f  Standard File Co
7720: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a  ntrol Opcodes.**
7730: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
7740: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
7750: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
7760: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7770: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
7780: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7790: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
77a0: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
77b0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
77c0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
77d0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
77e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
77f0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
7800: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
7810: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
7820: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
7830: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
7840: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
7850: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
7860: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
7870: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
7880: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7890: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
78a0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
78b0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
78c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
78d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
78e0: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
78f0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
7900: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
7910: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
7920: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
7930: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
7940: 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e  sting and only n
7950: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
7960: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
7970: 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69  _TEST.** is defi
7980: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ned..**.** The [
7990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
79a0: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
79b0: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
79c0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
79d0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
79e0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
79f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
7a00: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
7a10: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
7a20: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
7a30: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
7a40: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
7a50: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
7a60: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
7a70: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
7a80: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
7a90: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
7aa0: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
7ab0: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
7ac0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
7ad0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
7ae0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
7af0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
7b00: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
7b10: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7b20: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
7b30: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
7b40: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
7b50: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
7b60: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
7b70: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
7b80: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
7b90: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
7ba0: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
7bb0: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
7bc0: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
7bd0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7be0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
7bf0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
7c00: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
7c10: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
7c20: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
7c30: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
7c40: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
7c50: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
7c60: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
7c70: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
7c80: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
7c90: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
7ca0: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
7cb0: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
7cc0: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
7cd0: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
7ce0: 73 79 73 74 65 6d 73 2e 0a 2a 2f 0a 23 64 65 66  systems..*/.#def
7cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7d00: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
7d10: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
7d20: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
7d30: 46 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66  FILE      2.#def
7d40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
7d50: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
7d60: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
7d70: 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TE_LAST_ERRNO   
7d80: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
7d90: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
7da0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
7db0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
7dc0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
7dd0: 49 5a 45 20 20 20 20 20 20 20 36 0a 0a 2f 2a 0a  IZE       6../*.
7de0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
7df0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
7e00: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
7e10: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
7e20: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
7e30: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
7e40: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
7e50: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
7e60: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
7e70: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
7e80: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
7e90: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
7ea0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
7eb0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
7ec0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
7ed0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
7ee0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
7ef0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7f00: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
7f10: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
7f20: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
7f30: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
7f40: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
7f50: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
7f60: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
7f70: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
7f80: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
7f90: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
7fa0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
7fb0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
7fc0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
7fd0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
7fe0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
7ff0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8000: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8010: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
8020: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
8030: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
8040: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8050: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
8060: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
8070: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
8080: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
8090: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
80a0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
80b0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
80c0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
80d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
80e0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
80f0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
8100: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
8110: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
8120: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
8130: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
8140: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
8150: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
8160: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
8170: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
8180: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
8190: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
81a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
81b0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
81c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
81d0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
81e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
81f0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
8200: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
8210: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
8220: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
8230: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
8240: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
8250: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
8260: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
8270: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
8280: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
8290: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
82a0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
82b0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
82c0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
82d0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
82e0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
82f0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
8300: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
8310: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
8320: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
8330: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
8340: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
8350: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
8360: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
8370: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
8380: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8390: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
83a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
83b0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
83c0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
83d0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
83e0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
83f0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
8400: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8410: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8420: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8430: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8440: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8450: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8460: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8470: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8480: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8490: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
84a0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
84b0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
84c0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
84d0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
84e0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
84f0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
8500: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8510: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8520: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8530: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8540: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8550: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8560: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8570: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  **.** ^SQLite gu
8580: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
8590: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
85a0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
85b0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
85c0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
85d0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
85e0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
85f0: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
8600: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
8610: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
8620: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
8630: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
8640: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
8650: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
8660: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
8670: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
8680: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
8690: 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72  ** 10 alphanumer
86a0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
86b0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
86c0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
86d0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
86e0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
86f0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
8700: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
8710: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
8720: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
8730: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
8740: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
8750: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
8760: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
8770: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
8780: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
8790: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
87a0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
87b0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
87c0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
87d0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
87e0: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
87f0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
8800: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
8810: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
8820: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
8830: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
8840: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
8850: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
8860: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
8870: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
8880: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
8890: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
88a0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
88b0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
88c0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
88d0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
88e0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
88f0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
8900: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
8910: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
8920: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
8930: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
8940: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
8950: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
8960: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
8970: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
8980: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
8990: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
89a0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
89b0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
89c0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
89d0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
89e0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
89f0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
8a00: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
8a10: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
8a20: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
8a30: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
8a40: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
8a50: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
8a60: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
8a70: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
8a80: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
8a90: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
8aa0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
8ab0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
8ac0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
8ad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
8ae0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
8af0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8b00: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
8b10: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
8b20: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
8b30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
8b40: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
8b50: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
8b60: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
8b70: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
8b80: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
8b90: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
8ba0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
8bb0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
8bc0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
8bd0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
8be0: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
8bf0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8c00: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
8c10: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
8c20: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
8c30: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
8c40: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
8c50: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
8c60: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
8c70: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
8c80: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
8c90: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
8ca0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
8cb0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
8cc0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
8cd0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
8ce0: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
8cf0: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
8d00: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
8d10: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
8d20: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
8d30: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
8d40: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
8d50: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
8d60: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
8d70: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
8d80: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
8d90: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
8da0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
8db0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
8dc0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
8dd0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
8de0: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
8df0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
8e00: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
8e10: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
8e20: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
8e30: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
8e40: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8e50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
8e60: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
8e70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
8e80: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
8e90: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8ea0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
8eb0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
8ec0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
8ed0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
8ee0: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
8ef0: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
8f00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
8f10: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
8f20: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
8f30: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
8f40: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
8f50: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
8f60: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
8f70: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
8f80: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
8f90: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
8fa0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
8fb0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
8fc0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
8fd0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
8fe0: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
8ff0: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
9000: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
9010: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
9020: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
9030: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
9040: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
9050: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
9060: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
9070: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
9080: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9090: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
90a0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
90b0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
90c0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
90d0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
90e0: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
90f0: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
9100: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
9110: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
9120: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
9130: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
9140: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
9150: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
9160: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
9170: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
9180: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
9190: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
91a0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
91b0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
91c0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
91d0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
91e0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
91f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
9200: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
9210: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
9220: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
9230: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
9240: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
9250: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
9260: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
9270: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
9280: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
9290: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
92a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
92b0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
92c0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
92d0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
92e0: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
92f0: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
9300: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
9310: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
9320: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
9330: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
9340: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
9350: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
9360: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
9370: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
9380: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  en call..**.** ^
9390: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
93a0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
93b0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
93c0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
93d0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
93e0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
93f0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
9400: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9410: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
9420: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
9430: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
9440: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
9450: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
9460: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
9470: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
9480: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
9490: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
94a0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
94b0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
94c0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
94d0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
94e0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
94f0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
9500: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
9510: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
9520: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
9530: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
9540: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
9550: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
9560: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
9570: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
9580: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
9590: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
95a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
95b0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
95c0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
95d0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
95e0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
95f0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
9600: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
9610: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
9620: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
9630: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
9640: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
9650: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
9660: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
9670: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
9680: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
9690: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
96a0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
96b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
96c0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
96d0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
96e0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
96f0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
9700: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
9710: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
9720: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
9730: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
9740: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
9750: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
9760: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
9770: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
9780: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
9790: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
97a0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
97b0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
97c0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
97d0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
97e0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
97f0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
9800: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
9810: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
9820: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
9830: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
9840: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
9850: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
9860: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
9870: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
9880: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
9890: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
98a0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
98b0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
98c0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
98d0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
98e0: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
98f0: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
9900: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
9910: 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38 36   multipled by 86
9920: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
9930: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
9940: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
9950: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
9960: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
9970: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
9980: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
9990: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
99a0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
99b0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
99c0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
99d0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
99e0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
99f0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
9a00: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
9a10: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
9a20: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
9a30: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
9a40: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
9a50: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
9a60: 62 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ble..*/.typedef 
9a70: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9a80: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
9a90: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
9aa0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
9ab0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
9ac0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
9ad0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
9ae0: 72 65 6e 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69  rently 2) */.  i
9af0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
9b00: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
9b10: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
9b20: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
9b30: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
9b40: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
9b50: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
9b60: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
9b70: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
9b80: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
9b90: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
9ba0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
9bb0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
9bc0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
9bd0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
9be0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
9bf0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
9c00: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
9c10: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
9c20: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
9c30: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
9c40: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
9c50: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
9c60: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
9c70: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
9c80: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
9c90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
9ca0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
9cb0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9cc0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
9cd0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
9ce0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
9cf0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
9d00: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
9d10: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
9d20: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
9d30: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
9d40: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
9d50: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
9d60: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
9d70: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
9d80: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
9d90: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
9da0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
9db0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
9dc0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
9dd0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
9de0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
9df0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
9e00: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
9e10: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
9e20: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
9e30: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
9e40: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
9e50: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
9e60: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
9e70: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
9e80: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
9e90: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
9ea0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
9eb0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
9ec0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
9ed0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
9ee0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
9ef0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
9f00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
9f10: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
9f20: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
9f30: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
9f40: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
9f50: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
9f60: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
9f70: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
9f80: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
9f90: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
9fa0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
9fb0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
9fc0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
9fd0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
9fe0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
9ff0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
a000: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
a010: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
a020: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
a030: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
a040: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
a050: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
a060: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
a070: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
a080: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
a090: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
a0a0: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
a0b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a0c0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
a0d0: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
a0e0: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
a0f0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
a100: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
a110: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
a120: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
a130: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
a140: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
a150: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
a160: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
a170: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
a180: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
a190: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
a1a0: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
a1b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
a1c0: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
a1d0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
a1e0: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
a1f0: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
a200: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
a210: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
a220: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
a230: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
a240: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
a250: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
a260: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
a270: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
a280: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
a290: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
a2a0: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
a2b0: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
a2c0: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
a2d0: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
a2e0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
a2f0: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
a300: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
a310: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
a320: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
a330: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
a340: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
a350: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
a360: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
a370: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
a380: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
a390: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
a3a0: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
a3b0: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
a3c0: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
a3d0: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
a3e0: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
a3f0: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
a400: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
a410: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
a420: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
a430: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
a440: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
a450: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
a460: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
a470: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
a480: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
a490: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
a4a0: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
a4b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
a4c0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
a4d0: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
a4e0: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
a4f0: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
a500: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
a510: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
a520: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
a530: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
a540: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
a550: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
a560: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
a570: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
a580: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a590: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
a5a0: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
a5b0: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
a5c0: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
a5d0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
a5e0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
a5f0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
a600: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
a610: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
a620: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
a630: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
a640: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
a650: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
a660: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
a670: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
a680: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
a690: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
a6a0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
a6b0: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
a6c0: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
a6d0: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
a6e0: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
a6f0: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
a700: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
a710: 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63  s given no the c
a720: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
a730: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
a740: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
a750: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
a760: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
a770: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
a780: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
a790: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
a7a0: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
a7b0: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
a7c0: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
a7d0: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
a7e0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
a7f0: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
a800: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
a810: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
a820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
a830: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
a840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
a850: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
a860: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
a870: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
a880: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
a890: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
a8a0: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
a8b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
a8c0: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
a8d0: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
a8e0: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
a8f0: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
a900: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
a910: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
a920: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
a930: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
a940: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
a950: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
a960: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
a970: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
a980: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
a990: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
a9a0: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
a9b0: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
a9c0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
a9d0: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
a9e0: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
a9f0: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
aa00: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
aa10: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
aa20: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
aa30: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
aa40: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
aa50: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
aa60: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
aa70: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
aa80: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
aa90: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
aaa0: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
aab0: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
aac0: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
aad0: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
aae0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
aaf0: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
ab00: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
ab10: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
ab20: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
ab30: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
ab40: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
ab50: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
ab60: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
ab70: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
ab80: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
ab90: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
aba0: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
abb0: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
abc0: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
abd0: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
abe0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
abf0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ac00: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
ac10: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
ac20: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ac30: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
ac40: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
ac50: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
ac60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
ac70: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
ac80: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
ac90: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
aca0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
acb0: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
acc0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
acd0: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
ace0: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
acf0: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
ad00: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
ad10: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
ad20: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
ad30: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ad40: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
ad50: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
ad60: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
ad70: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
ad80: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
ad90: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
ada0: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
adb0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
adc0: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
add0: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
ade0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
adf0: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
ae00: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
ae10: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
ae20: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
ae30: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
ae40: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
ae50: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
ae60: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
ae70: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
ae80: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
ae90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
aea0: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
aeb0: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
aec0: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
aed0: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
aee0: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
aef0: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
af00: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
af10: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
af20: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
af30: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
af40: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
af50: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
af60: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
af70: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
af80: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
af90: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
afa0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
afb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
afc0: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
afd0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
afe0: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
aff0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
b000: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
b010: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
b020: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
b030: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
b040: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
b050: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
b060: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
b070: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
b080: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
b090: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
b0a0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b0b0: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
b0c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
b0d0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
b0e0: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
b0f0: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
b100: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
b110: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
b120: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
b130: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
b140: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
b150: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
b160: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b170: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
b180: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
b190: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
b1a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
b1b0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
b1c0: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
b1d0: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
b1e0: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
b1f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
b200: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
b210: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
b220: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
b230: 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
b240: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b250: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
b260: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
b270: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
b280: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
b290: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
b2a0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
b2b0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
b2c0: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
b2d0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
b2e0: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
b2f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
b300: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
b310: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
b320: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
b330: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
b340: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
b350: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
b360: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
b370: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
b380: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
b390: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
b3a0: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
b3b0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
b3c0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
b3d0: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
b3e0: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
b3f0: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
b400: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
b410: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
b420: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
b430: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b440: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
b450: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
b460: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
b470: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
b480: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
b490: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
b4a0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
b4b0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
b4c0: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
b4d0: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
b4e0: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
b4f0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
b500: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
b510: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
b520: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
b530: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
b540: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
b550: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
b560: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
b570: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
b580: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
b590: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
b5a0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
b5b0: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
b5c0: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
b5d0: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
b5e0: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
b5f0: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
b600: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
b610: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
b620: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
b630: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
b640: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
b650: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
b660: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
b670: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
b680: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
b690: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
b6a0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
b6b0: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
b6c0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
b6d0: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
b6e0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
b6f0: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
b700: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b710: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
b720: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
b730: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
b740: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
b750: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b760: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
b770: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
b780: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
b790: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
b7a0: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
b7b0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
b7c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
b7d0: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
b7e0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
b7f0: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
b800: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
b810: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
b820: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
b830: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
b840: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
b850: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
b860: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
b870: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
b880: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
b890: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
b8a0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
b8b0: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
b8c0: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
b8d0: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
b8e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
b8f0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
b900: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
b910: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
b920: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
b930: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
b940: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
b950: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
b960: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
b970: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
b980: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
b990: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
b9a0: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
b9b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  int sqlite3_init
b9c0: 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e  ialize(void);.in
b9d0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
b9e0: 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  wn(void);.int sq
b9f0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
ba00: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
ba10: 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a  _os_end(void);..
ba20: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ba30: 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20  Configuring The 
ba40: 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a  SQLite Library.*
ba50: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
ba60: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
ba70: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
ba80: 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69  ake global confi
ba90: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
baa0: 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e  ges to SQLite in
bab0: 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53   order to tune S
bac0: 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65  QLite to the spe
bad0: 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a  cific needs of.*
bae0: 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
baf0: 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  n.  The default 
bb00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73  configuration is
bb10: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
bb20: 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
bb30: 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69  tions and so thi
bb40: 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75  s routine is usu
bb50: 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61  ally not necessa
bb60: 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72  ry.  It is.** pr
bb70: 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72  ovided to suppor
bb80: 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69  t rare applicati
bb90: 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c  ons with unusual
bba0: 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68   needs..**.** Th
bbb0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
bbc0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
bbd0: 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
bbe0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
bbf0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20  .** must insure 
bc00: 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51  that no other SQ
bc10: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
bc20: 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f  are invoked by o
bc30: 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20  ther.** threads 
bc40: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  while sqlite3_co
bc50: 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e  nfig() is runnin
bc60: 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c  g.  Furthermore,
bc70: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
bc80: 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ).** may only be
bc90: 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74   invoked prior t
bca0: 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61  o library initia
bcb0: 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  lization using.*
bcc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  * [sqlite3_initi
bcd0: 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
bce0: 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73  r shutdown by [s
bcf0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
bd00: 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  )]..** ^If sqlit
bd10: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63  e3_config() is c
bd20: 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
bd30: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bd40: 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a  )] and before.**
bd50: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
bd60: 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69  wn()] then it wi
bd70: 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ll return SQLITE
bd80: 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65  _MISUSE..** Note
bd90: 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20  , however, that 
bda0: 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  ^sqlite3_config(
bdb0: 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  ) can be called 
bdc0: 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a  as part of the.*
bdd0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
bde0: 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   of an applicati
bdf0: 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69  on-defined [sqli
be00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a  te3_os_init()]..
be10: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
be20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
be30: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
be40: 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  an integer.** [S
be50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
be60: 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66  GLETHREAD | conf
be70: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
be80: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
be90: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
bea0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
beb0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
bec0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
bed0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
bee0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
bef0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
bf00: 53 49 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63  SINGLETHREAD | c
bf10: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
bf20: 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
bf30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
bf40: 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
bf50: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
bf60: 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
bf70: 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
bf80: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
bf90: 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
bfa0: 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
bfb0: 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
bfc0: 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
bfd0: 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
bfe0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
bff0: 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
c000: 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20  r code]..*/.int 
c010: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
c020: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
c030: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
c040: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
c050: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
c060: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
c070: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
c080: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
c090: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
c0a0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
c0b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
c0c0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
c0d0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
c0e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
c0f0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
c100: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
c110: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
c120: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
c130: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
c140: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
c150: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 20  irst argument). 
c160: 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   The.** sqlite3_
c170: 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
c180: 72 66 61 63 65 20 73 68 6f 75 6c 64 20 6f 6e 6c  rface should onl
c190: 79 20 62 65 20 75 73 65 64 20 69 6d 6d 65 64 69  y be used immedi
c1a0: 61 74 65 6c 79 20 61 66 74 65 72 0a 2a 2a 20 74  ately after.** t
c1b0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
c1c0: 65 63 74 69 6f 6e 20 69 73 20 63 72 65 61 74 65  ection is create
c1d0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c1e0: 5f 6f 70 65 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _open()],.** [sq
c1f0: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
c200: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c210: 6e 5f 76 32 28 29 5d 2e 20 20 0a 2a 2a 0a 2a 2a  n_v2()].  .**.**
c220: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
c230: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c240: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
c250: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  .)  is the.** co
c260: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
c270: 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
c280: 64 65 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  de that indicate
c290: 73 20 77 68 61 74 0a 2a 2a 20 61 73 70 65 63 74  s what.** aspect
c2a0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
c2b0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
c2c0: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
c2d0: 64 2e 0a 2a 2a 20 54 68 65 20 6f 6e 6c 79 20 63  d..** The only c
c2e0: 68 6f 69 63 65 20 66 6f 72 20 74 68 69 73 20 76  hoice for this v
c2f0: 61 6c 75 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  alue is [SQLITE_
c300: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
c310: 44 45 5d 2e 0a 2a 2a 20 4e 65 77 20 76 65 72 62  DE]..** New verb
c320: 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20  s are likely to 
c330: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
c340: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
c350: 51 4c 69 74 65 2e 0a 2a 2a 20 41 64 64 69 74 69  QLite..** Additi
c360: 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 64  onal arguments d
c370: 65 70 65 6e 64 20 6f 6e 20 74 68 65 20 76 65 72  epend on the ver
c380: 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
c390: 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
c3a0: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
c3b0: 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
c3c0: 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
c3d0: 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
c3e0: 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
c3f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
c400: 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
c410: 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
c420: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
c430: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
c440: 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
c450: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
c460: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
c470: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
c480: 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
c490: 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
c4a0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
c4b0: 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
c4c0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
c4d0: 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
c4e0: 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
c4f0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
c500: 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
c510: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
c520: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
c530: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
c540: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
c550: 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
c560: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
c570: 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
c580: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
c590: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
c5a0: 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
c5b0: 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
c5c0: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
c5d0: 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
c5e0: 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
c5f0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
c600: 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
c610: 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
c620: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
c630: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
c640: 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
c650: 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
c660: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
c670: 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
c680: 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
c690: 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
c6a0: 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
c6b0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
c6c0: 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
c6d0: 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
c6e0: 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
c6f0: 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
c700: 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
c710: 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
c720: 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
c730: 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
c740: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
c750: 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
c760: 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
c770: 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
c780: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
c790: 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
c7a0: 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
c7b0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
c7c0: 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
c7d0: 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
c7e0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
c7f0: 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
c800: 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
c810: 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
c820: 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
c830: 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
c840: 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
c850: 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
c860: 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
c870: 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
c880: 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
c890: 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
c8a0: 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
c8b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
c8c0: 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d 65  loc and xFree me
c8d0: 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20  thods must work 
c8e0: 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c  like the.** mall
c8f0: 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
c900: 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
c910: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
c920: 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78 52  brary..** The xR
c930: 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d 75  ealloc method mu
c940: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65 61  st work like rea
c950: 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65 20  lloc() from the 
c960: 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
c970: 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 65  ry.** with the e
c980: 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69 66  xception that if
c990: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
c9a0: 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f 63  ment to xRealloc
c9b0: 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52 65   is zero,.** xRe
c9c0: 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61 20  alloc must be a 
c9d0: 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74 20  no-op - it must 
c9e0: 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79 20  not perform any 
c9f0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a 2a  allocation or.**
ca00: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20   deallocation.  
ca10: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
ca20: 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
ca30: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
ca40: 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
ca50: 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
ca60: 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
ca70: 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
ca80: 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e 20  p..** And so in 
ca90: 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f 75  cases where xRou
caa0: 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74 75  ndup always retu
cab0: 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
cac0: 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c 6c  umber,.** xReall
cad0: 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20 65  oc can perform e
cae0: 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73 74  xactly as the st
caf0: 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20 72  andard library r
cb00: 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a 20  ealloc() and.** 
cb10: 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d 70  still be in comp
cb20: 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69 73  liance with this
cb30: 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e 0a   specification..
cb40: 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75  **.** xSize shou
cb50: 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c  ld return the al
cb60: 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20  located size of 
cb70: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
cb80: 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  ion.** previousl
cb90: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
cba0: 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c  xMalloc or xReal
cbb0: 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61  loc.  The alloca
cbc0: 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61  ted size.** is a
cbd0: 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61  lways at least a
cbe0: 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71  s big as the req
cbf0: 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20  uested size but 
cc00: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a  may be larger..*
cc10: 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75  *.** The xRoundu
cc20: 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  p method returns
cc30: 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74   what would be t
cc40: 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
cc50: 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79  e of.** a memory
cc60: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65   allocation give
cc70: 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  n a particular r
cc80: 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20  equested size.  
cc90: 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  Most memory.** a
cca0: 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
ccb0: 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  up memory alloca
ccc0: 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74  tions at least t
ccd0: 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69  o the next multi
cce0: 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f  ple.** of 8.  So
ccf0: 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  me allocators ro
cd00: 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67  und up to a larg
cd10: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74  er multiple or t
cd20: 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a  o a power of 2..
cd30: 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20  ** Every memory 
cd40: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65  allocation reque
cd50: 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72  st coming in thr
cd60: 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61  ough [sqlite3_ma
cd70: 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  lloc()].** or [s
cd80: 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
cd90: 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52  ] first calls xR
cda0: 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75  oundup.  If xRou
cdb0: 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20  ndup returns 0, 
cdc0: 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20  .** that causes 
cdd0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
cde0: 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  g memory allocat
cdf0: 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a  ion to fail..**.
ce00: 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74  ** The xInit met
ce10: 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  hod initializes 
ce20: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
ce30: 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d  ator.  (For exam
ce40: 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
ce50: 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
ce60: 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
ce70: 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
ce80: 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
ce90: 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
cea0: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
ceb0: 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
cec0: 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
ced0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
cee0: 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
cef0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
cf00: 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
cf10: 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
cf20: 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
cf30: 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
cf40: 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
cf50: 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
cf60: 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
cf70: 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
cf80: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
cf90: 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
cfa0: 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
cfb0: 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
cfc0: 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
cfd0: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
cfe0: 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
cff0: 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
d000: 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
d010: 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
d020: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
d030: 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
d040: 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
d050: 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
d060: 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
d070: 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
d080: 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
d090: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
d0a0: 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
d0b0: 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
d0c0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
d0d0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
d0e0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d0f0: 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
d100: 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
d110: 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
d120: 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
d130: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
d140: 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
d150: 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
d160: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
d170: 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
d180: 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
d190: 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
d1a0: 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
d1b0: 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
d1c0: 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
d1d0: 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
d1e0: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
d1f0: 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
d200: 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
d210: 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
d220: 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
d230: 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
d240: 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
d250: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
d260: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
d270: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
d280: 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
d290: 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
d2a0: 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
d2b0: 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
d2c0: 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
d2d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
d2e0: 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
d2f0: 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
d300: 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
d310: 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
d320: 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
d330: 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
d340: 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
d350: 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
d360: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
d370: 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
d380: 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
d390: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
d3a0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
d3b0: 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
d3c0: 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
d3d0: 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
d3e0: 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
d3f0: 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
d400: 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
d410: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
d420: 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
d430: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
d440: 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
d450: 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
d460: 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
d470: 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
d480: 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
d490: 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
d4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
d4b0: 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
d4c0: 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
d4d0: 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
d4e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
d4f0: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
d500: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  ns.**.** These c
d510: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
d520: 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
d530: 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
d540: 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
d550: 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
d560: 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
d570: 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
d580: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
d590: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
d5a0: 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
d5b0: 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
d5c0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
d5d0: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
d5e0: 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
d5f0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d600: 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
d610: 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
d620: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
d630: 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
d640: 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
d650: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
d660: 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
d670: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
d680: 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
d690: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
d6a0: 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
d6b0: 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
d6c0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
d6d0: 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
d6e0: 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
d6f0: 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
d700: 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
d710: 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
d720: 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
d730: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
d740: 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
d750: 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
d760: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
d770: 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
d780: 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
d790: 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
d7a0: 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72  e] to Single-thr
d7b0: 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
d7c0: 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
d7d0: 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e  s.** all mutexin
d7e0: 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74  g and puts SQLit
d7f0: 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68  e into a mode wh
d800: 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20  ere it can only 
d810: 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20  be used.** by a 
d820: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
d830: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
d840: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
d850: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
d860: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
d870: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
d880: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
d890: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
d8a0: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
d8b0: 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65  change the [thre
d8c0: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d  ading mode] from
d8d0: 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20   its default.** 
d8e0: 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d  value of Single-
d8f0: 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73  thread and so [s
d900: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
d910: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a   will return .**
d920: 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
d930: 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
d940: 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
d950: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a  _SINGLETHREAD.**
d960: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d970: 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
d980: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
d990: 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c  FIG_MULTITHREAD<
d9a0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
d9b0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
d9c0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
d9d0: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
d9e0: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
d9f0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
da00: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20   Multi-thread.  
da10: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
da20: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d  it disables.** m
da30: 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61  utexing on [data
da40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
da50: 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
da60: 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
da70: 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  s..** The applic
da80: 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73  ation is respons
da90: 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69  ible for seriali
daa0: 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a  zing access to.*
dab0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
dac0: 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
dad0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
dae0: 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d  s].  But other m
daf0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
db00: 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51  abled so that SQ
db10: 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66  Lite will be saf
db20: 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75  e to use in a mu
db30: 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  lti-threaded.** 
db40: 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c  environment as l
db50: 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68  ong as no two th
db60: 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f  reads attempt to
db70: 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a   use the same.**
db80: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
db90: 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61  ction] at the sa
dba0: 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51  me time.  ^If SQ
dbb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
dbc0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
dbd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
dbe0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
dbf0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
dc00: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
dc10: 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
dc20: 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
dc30: 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   Multi-thread [t
dc40: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
dc50: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
dc60: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
dc70: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
dc80: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
dc90: 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
dca0: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
dcb0: 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  EAD configuratio
dcc0: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
dcd0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
dce0: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
dcf0: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
dd00: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
dd10: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
dd20: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
dd30: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
dd40: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
dd50: 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
dd60: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
dd70: 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
dd80: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
dd90: 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
dda0: 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
ddb0: 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
ddc0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
ddd0: 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
dde0: 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
ddf0: 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
de00: 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
de10: 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
de20: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
de30: 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
de40: 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
de50: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
de60: 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
de70: 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
de80: 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
de90: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
dea0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
deb0: 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
dec0: 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
ded0: 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
dee0: 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
def0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
df00: 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
df10: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
df20: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
df30: 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
df40: 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
df50: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
df60: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
df70: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
df80: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
df90: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
dfa0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
dfb0: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
dfc0: 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
dfd0: 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
dfe0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
dff0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
e000: 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
e010: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
e020: 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
e030: 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
e040: 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
e050: 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
e060: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
e070: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e080: 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
e090: 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
e0a0: 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
e0b0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
e0c0: 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
e0d0: 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
e0e0: 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
e0f0: 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
e100: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
e110: 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
e120: 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
e130: 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
e140: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
e150: 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
e160: 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
e170: 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
e180: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
e190: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
e1a0: 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
e1b0: 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
e1c0: 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
e1d0: 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
e1e0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
e1f0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
e200: 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
e210: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e220: 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
e230: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e240: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
e250: 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
e260: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
e270: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
e280: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
e290: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
e2a0: 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
e2b0: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
e2c0: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
e2d0: 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71  ucture.  The [sq
e2e0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
e2f0: 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  s].** structure 
e300: 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74  is filled with t
e310: 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  he currently def
e320: 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ined memory allo
e330: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
e340: 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
e350: 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
e360: 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
e370: 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
e380: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
e390: 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
e3a0: 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69  er that simulati
e3b0: 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ons memory alloc
e3c0: 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72  ation failure or
e3d0: 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72  .** tracks memor
e3e0: 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61  y usage, for exa
e3f0: 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  mple. </dd>.**.*
e400: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
e410: 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
e420: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
e430: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
e440: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
e450: 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
e460: 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
e470: 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
e480: 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
e490: 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
e4a0: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
e4b0: 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
e4c0: 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
e4d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e4e0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
e4f0: 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
e500: 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
e510: 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
e520: 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
e530: 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
e540: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
e550: 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
e560: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
e570: 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
e580: 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
e590: 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
e5a0: 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
e5b0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
e5c0: 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
e5d0: 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
e5e0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
e5f0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
e600: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
e610: 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
e620: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
e630: 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
e640: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
e650: 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
e660: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
e670: 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
e680: 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
e690: 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
e6a0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
e6b0: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
e6c0: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
e6d0: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
e6e0: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
e6f0: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
e700: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
e710: 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
e720: 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
e730: 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
e740: 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  s:  A pointer an
e750: 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
e760: 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
e770: 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
e780: 73 63 72 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f  scrach allocatio
e790: 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72  ns will be.** dr
e7a0: 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  awn, the size of
e7b0: 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c   each scratch al
e7c0: 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a  location (sz),.*
e7d0: 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  * and the maximu
e7e0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61  m number of scra
e7f0: 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
e800: 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
e810: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
e820: 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
e830: 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  6..** The first 
e840: 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
e850: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
e860: 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
e870: 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
e880: 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
e890: 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
e8a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
e8b0: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f  no more than two
e8c0: 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
e8d0: 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f   per thread.  So
e8e0: 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
e8f0: 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65  set to twice the
e900: 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
e910: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
e920: 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ads..** ^SQLite 
e930: 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69  will never requi
e940: 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66  re a scratch buf
e950: 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
e960: 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
e970: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
e980: 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c  ge size. ^If SQL
e990: 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20  ite needs needs 
e9a0: 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63  additional.** sc
e9b0: 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
e9c0: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
e9d0: 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
e9e0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e9f0: 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
ea00: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
ea10: 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
ea20: 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
ea30: 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
ea40: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
ea50: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
ea60: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
ea70: 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
ea80: 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
ea90: 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
eaa0: 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
eab0: 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
eac0: 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
ead0: 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
eae0: 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
eaf0: 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  enation.  .** Th
eb00: 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
eb10: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
eb20: 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
eb30: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
eb40: 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
eb50: 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
eb60: 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
eb70: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
eb80: 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68  HE option..** Th
eb90: 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
eba0: 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
ebb0: 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65  option: A pointe
ebc0: 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67  r to 8-byte alig
ebd0: 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74  ned.** memory, t
ebe0: 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  he size of each 
ebf0: 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29  page buffer (sz)
ec00: 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72  , and the number
ec10: 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a   of pages (N)..*
ec20: 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e  * The sz argumen
ec30: 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
ec40: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67  size of the larg
ec50: 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67  est database pag
ec60: 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66  e.** (a power of
ec70: 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32   two between 512
ec80: 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73   and 32768) plus
ec90: 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20   a little extra 
eca0: 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
ecb0: 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70   header.  ^The p
ecc0: 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20  age header size 
ecd0: 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65  is 20 to 40 byte
ece0: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a  s depending on.*
ecf0: 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69  * the host archi
ed00: 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73  tecture.  ^It is
ed10: 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74   harmless, apart
ed20: 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64   from the wasted
ed30: 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d   memory,.** to m
ed40: 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20  ake sz a little 
ed50: 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20  too large.  The 
ed60: 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
ed70: 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74  t should point t
ed80: 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  o an allocation 
ed90: 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e  of at least sz*N
eda0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
edb0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
edc0: 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  l use the memory
edd0: 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
ede0: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
edf0: 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a  to satisfy its.*
ee00: 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66  * memory needs f
ee10: 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70  or the first N p
ee20: 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64  ages that it add
ee30: 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66  s to cache.  ^If
ee40: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70   additional.** p
ee50: 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
ee60: 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e   is needed beyon
ee70: 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
ee80: 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f  ed by this optio
ee90: 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  n, then.** SQLit
eea0: 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
eeb0: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72  e3_malloc()] for
eec0: 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20   the additional 
eed0: 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a  storage space..*
eee0: 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e  * The pointer in
eef0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
ef00: 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61  ent must.** be a
ef10: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
ef20: 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  yte boundary or 
ef30: 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
ef40: 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
ef50: 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
ef60: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
ef70: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
ef80: 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
ef90: 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
efa0: 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
efb0: 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
efc0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
efd0: 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
efe0: 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
eff0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f000: 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
f010: 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
f020: 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
f030: 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
f040: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
f050: 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
f060: 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
f070: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
f080: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
f090: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
f0a0: 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
f0b0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
f0c0: 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
f0d0: 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
f0e0: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
f0f0: 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
f100: 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
f110: 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
f120: 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
f130: 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
f140: 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
f150: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
f160: 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
f170: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
f180: 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
f190: 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
f1a0: 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
f1b0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
f1c0: 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
f1d0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
f1e0: 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
f1f0: 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
f200: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
f210: 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
f220: 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
f230: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
f240: 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
f250: 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
f260: 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
f270: 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
f280: 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
f290: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
f2a0: 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
f2b0: 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
f2c0: 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
f2d0: 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
f2e0: 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
f2f0: 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
f300: 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
f310: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
f320: 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a  undefined.</dd>.
f330: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
f340: 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
f350: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
f360: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
f370: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
f380: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
f390: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
f3a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
f3b0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
f3c0: 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
f3d0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
f3e0: 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
f3f0: 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
f400: 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
f410: 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
f420: 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
f430: 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
f440: 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
f450: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
f460: 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63  copy of the.** c
f470: 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
f480: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
f490: 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
f4a0: 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
f4b0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
f4c0: 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
f4d0: 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
f4e0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
f4f0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
f500: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
f510: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
f520: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
f530: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
f540: 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
f550: 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
f560: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
f570: 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
f580: 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
f590: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
f5a0: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
f5b0: 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
f5c0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
f5d0: 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
f5e0: 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
f5f0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
f600: 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
f610: 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
f620: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
f630: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
f640: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
f650: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
f660: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
f670: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
f680: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
f690: 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  ure.  The.** [sq
f6a0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
f6b0: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
f6c0: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
f6d0: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
f6e0: 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75  efined mutex rou
f6f0: 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
f700: 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
f710: 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
f720: 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65  the default mute
f730: 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  x allocation.** 
f740: 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
f750: 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20  wrapper used to 
f760: 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67  track mutex usag
f770: 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63  e for performanc
f780: 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f  e.** profiling o
f790: 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65  r testing, for e
f7a0: 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51  xample.   ^If SQ
f7b0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
f7c0: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
f7d0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
f7e0: 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
f7f0: 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
f800: 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
f810: 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
f820: 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
f830: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
f840: 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
f850: 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
f860: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f870: 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
f880: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
f890: 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  TEX configuratio
f8a0: 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a  n option will.**
f8b0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
f8c0: 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ERROR].</dd>.**.
f8d0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
f8e0: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
f8f0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
f900: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
f910: 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
f920: 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
f930: 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
f940: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
f950: 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
f960: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
f970: 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
f980: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f990: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
f9a0: 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
f9b0: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
f9c0: 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
f9d0: 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
f9e0: 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
f9f0: 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
fa00: 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
fa10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
fa20: 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
fa30: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
fa40: 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
fa50: 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
fa60: 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
fa70: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
fa80: 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
fa90: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
faa0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
fab0: 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
fac0: 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
fad0: 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
fae0: 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
faf0: 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  )^ </dd>.**.** <
fb00: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
fb10: 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  _PCACHE</dt>.** 
fb20: 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
fb30: 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
fb40: 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
fb50: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
fb60: 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  .** an [sqlite3_
fb70: 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
fb80: 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
fb90: 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
fba0: 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
fbb0: 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
fbc0: 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
fbd0: 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74  ation.)^  ^SQLit
fbe0: 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
fbf0: 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
fc00: 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
fc10: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
fc20: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
fc30: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
fc40: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
fc50: 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
fc60: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
fc70: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
fc80: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
fc90: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
fca0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
fcb0: 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  ache_methods] ob
fcc0: 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
fcd0: 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72  pies of the curr
fce0: 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68  ent.** page cach
fcf0: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
fd00: 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
fd10: 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
fd20: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
fd30: 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
fd40: 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
fd50: 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
fd60: 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
fd70: 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
fd80: 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
fd90: 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
fda0: 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
fdb0: 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
fdc0: 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
fdd0: 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
fde0: 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
fdf0: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
fe00: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
fe10: 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
fe20: 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
fe30: 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
fe40: 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
fe50: 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
fe60: 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
fe70: 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
fe80: 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
fe90: 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
fea0: 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
feb0: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
fec0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
fed0: 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
fee0: 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
fef0: 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
ff00: 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
ff10: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
ff20: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
ff30: 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
ff40: 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
ff50: 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
ff60: 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
ff70: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
ff80: 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
ff90: 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
ffa0: 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
ffb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
ffc0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
ffd0: 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
ffe0: 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
fff0: 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
10000 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
10010 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
10020 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
10030 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
10040 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
10050 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
10060 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
10070 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
10080 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
10090 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
100a0 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
100b0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
100c0 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
100d0 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
100e0 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
100f0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
10100 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
10110 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
10120 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
10130 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
10140 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
10150 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
10160 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
10170 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
10180 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  e. </dd>.**.** <
10190 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
101a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
101b0 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
101c0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
101d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
101e0 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
101f0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
10200 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10210 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
10220 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
10230 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10240 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
10250 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
10260 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
10270 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
10280 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
10290 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
102a0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
102b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
102c0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
102d0 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
102e0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
102f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10300 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
10310 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
10320 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
10330 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10340 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
10350 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
10360 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
10370 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
10380 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10390 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
103a0 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
103b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
103c0 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
103d0 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
103e0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
103f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10400 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
10410 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
10420 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
10430 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
10440 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
10450 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
10460 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
10470 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
10480 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10490 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
104a0 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
104b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
104c0 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
104d0 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74 65 33    14  /* sqlite3
104e0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
104f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10500 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
10510 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 73 71  CHE    15  /* sq
10520 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
10530 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
10540 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
10550 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
10560 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
10570 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
10580 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
10590 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
105a0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
105b0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
105c0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
105d0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
105e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
105f0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
10600 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
10610 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
10620 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
10630 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
10640 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
10650 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
10660 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
10670 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
10680 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
10690 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
106a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
106b0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
106c0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
106d0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
106e0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
106f0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
10700 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
10710 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
10720 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
10730 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
10740 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
10750 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10760 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
10770 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
10780 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
10790 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
107a0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
107b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
107c0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
107d0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
107e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
107f0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
10800 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
10810 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
10820 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
10830 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
10840 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
10850 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
10860 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
10870 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
10880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10890 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
108a0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
108b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
108c0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
108d0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
108e0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
108f0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
10900 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
10910 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
10920 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
10930 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
10940 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
10950 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
10960 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
10970 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
10980 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
10990 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
109a0 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
109b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
109c0 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
109d0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
109e0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
109f0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
10a00 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
10a10 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
10a20 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
10a30 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
10a40 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
10a50 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
10a60 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
10a70 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
10a80 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
10a90 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
10aa0 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
10ab0 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
10ac0 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
10ad0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
10ae0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
10af0 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
10b00 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
10b10 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
10b20 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
10b30 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
10b40 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
10b50 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
10b60 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
10b70 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
10b80 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
10b90 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
10ba0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
10bb0 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
10bc0 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
10bd0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
10be0 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
10bf0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
10c00 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
10c10 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
10c20 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
10c30 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
10c40 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
10c50 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
10c60 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
10c70 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
10c80 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
10c90 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
10ca0 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
10cb0 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
10cc0 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
10cd0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
10ce0 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
10cf0 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
10d00 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
10d10 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
10d20 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
10d30 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
10d40 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
10d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
10d60 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
10d70 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f  E    1001  /* vo
10d80 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 0a  id* int int */..
10d90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10da0 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
10db0 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
10dc0 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e  lt Codes.**.** ^
10dd0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
10de0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
10df0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
10e00 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
10e10 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
10e20 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
10e30 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
10e40 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
10e50 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
10e60 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
10e70 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
10e80 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
10e90 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
10ea0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
10eb0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
10ec0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
10ed0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10ee0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
10ef0 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
10f00 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
10f10 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
10f20 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
10f30 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
10f40 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
10f50 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
10f60 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
10f70 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
10f80 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
10f90 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
10fa0 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
10fb0 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
10fc0 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
10fd0 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
10fe0 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
10ff0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
11000 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
11010 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
11020 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
11030 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
11040 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
11050 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
11060 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
11070 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  id..**.** ^This 
11080 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
11090 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
110a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
110b0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
110c0 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
110d0 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
110e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
110f0 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
11100 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
11110 20 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73    ^If no success
11120 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
11130 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
11140 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
11150 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
11160 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
11170 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  d..**.** ^(If an
11180 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
11190 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
111a0 72 2c 20 74 68 65 6e 20 74 68 65 20 5b 72 6f 77  r, then the [row
111b0 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72  id] of the inser
111c0 74 65 64 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65  ted.** row is re
111d0 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 72  turned by this r
111e0 6f 75 74 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61  outine as long a
111f0 73 20 74 68 65 20 74 72 69 67 67 65 72 20 69 73  s the trigger is
11200 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
11210 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
11220 72 20 74 65 72 6d 69 6e 61 74 65 73 2c 20 74 68  r terminates, th
11230 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
11240 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
11250 0a 2a 2a 20 72 65 76 65 72 74 73 20 74 6f 20 74  .** reverts to t
11260 68 65 20 6c 61 73 74 20 76 61 6c 75 65 20 69 6e  he last value in
11270 73 65 72 74 65 64 20 62 65 66 6f 72 65 20 74 68  serted before th
11280 65 20 74 72 69 67 67 65 72 20 66 69 72 65 64 2e  e trigger fired.
11290 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
112a0 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
112b0 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
112c0 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
112d0 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
112e0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
112f0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
11300 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
11310 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
11320 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
11330 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
11340 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
11350 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
11360 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
11370 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
11380 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
11390 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
113a0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
113b0 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
113c0 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
113d0 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
113e0 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
113f0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
11400 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
11410 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
11420 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
11430 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
11440 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
11450 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
11460 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
11470 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
11480 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
11490 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
114a0 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
114b0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
114c0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
114d0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
114e0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
114f0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
11500 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
11510 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
11520 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
11530 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
11540 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
11550 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
11560 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
11570 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
11580 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
11590 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
115a0 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
115b0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
115c0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
115d0 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
115e0 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
115f0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
11600 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
11610 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
11620 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
11630 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
11640 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
11650 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
11660 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
11670 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
11680 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
11690 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
116a0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
116b0 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
116c0 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
116d0 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
116e0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
116f0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
11700 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
11710 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
11720 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
11730 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
11740 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11750 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
11760 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
11770 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
11780 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
11790 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
117a0 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
117b0 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
117c0 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  ** or inserted o
117d0 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
117e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
117f0 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61  ompleted SQL sta
11800 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65  tement.** on the
11810 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11820 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
11830 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
11840 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e  rameter..** ^(On
11850 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
11860 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
11870 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
11880 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
11890 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
118a0 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
118b0 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
118c0 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
118d0 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
118e0 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   or [foreign key
118f0 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f   actions] are no
11900 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65  t counted.)^ Use
11910 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
11920 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
11930 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69  ] function to fi
11940 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
11950 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a  ber of changes.*
11960 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  * including chan
11970 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
11980 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69  iggers and forei
11990 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a  gn key actions..
119a0 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74  **.** ^Changes t
119b0 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
119c0 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61  e simulated by a
119d0 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
119e0 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f  igger].** are no
119f0 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79  t counted.  Only
11a00 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e   real table chan
11a10 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ges are counted.
11a20 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20  .**.** ^(A "row 
11a30 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
11a40 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
11a50 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
11a60 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
11a70 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
11a80 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
11a90 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
11aa0 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
11ab0 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
11ac0 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45  ects of [REPLACE
11ad0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
11ae0 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
11af0 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
11b00 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41  essing, [DROP TA
11b10 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20  BLE], or by any 
11b20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
11b30 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
11b40 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
11b50 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  hanges.)^.**.** 
11b60 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
11b70 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
11b80 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
11b90 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
11ba0 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
11bb0 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45  ipt of a [CREATE
11bc0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
11bd0 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51  er]. .** Most SQ
11be0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
11bf0 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
11c00 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
11c10 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
11c20 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
11c30 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
11c40 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
11c50 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
11c60 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
11c70 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
11c80 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
11c90 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
11ca0 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
11cb0 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
11cc0 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
11cd0 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
11ce0 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
11cf0 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  * ^Calling [sqli
11d00 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
11d10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
11d20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
11d30 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
11d40 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
11d50 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  text..**.** ^Thi
11d60 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
11d70 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
11d80 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
11d90 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
11da0 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
11db0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
11dc0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
11dd0 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
11de0 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
11df0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77  ..**.** ^Thus, w
11e00 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
11e10 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74  the top level, t
11e20 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
11e30 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
11e40 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
11e50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
11e60 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
11e70 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
11e80 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64  at also occurred
11e90 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65   at the top leve
11ea0 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65  l.  ^(Within the
11eb0 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
11ec0 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
11ed0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
11ee0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
11ef0 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
11f00 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
11f10 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
11f20 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
11f30 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
11f40 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
11f50 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
11f60 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
11f70 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
11f80 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
11f90 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
11fa0 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
11fb0 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
11fc0 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
11fd0 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
11fe0 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
11ff0 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  ntext.)^.**.** S
12000 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
12010 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12020 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
12030 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
12040 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
12050 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
12060 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
12070 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
12080 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
12090 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
120a0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
120b0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
120c0 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
120d0 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
120e0 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
120f0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
12100 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
12110 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
12120 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
12130 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
12140 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
12150 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
12160 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
12170 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
12180 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
12190 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
121a0 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
121b0 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a  d by [INSERT],.*
121c0 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  * [UPDATE] or [D
121d0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
121e0 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
121f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12200 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
12210 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74   ^(The count ret
12220 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
12230 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
12240 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68   includes all ch
12250 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c  anges.** from al
12260 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  l [CREATE TRIGGE
12270 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e  R | trigger] con
12280 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65  texts and change
12290 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f  s made by.** [fo
122a0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
122b0 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  s]. However,.** 
122c0 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
122d0 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
122e0 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  es used to imple
122f0 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63  ment [REPLACE] c
12300 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64  onstraints,.** d
12310 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
12320 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
12330 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d   or [DROP TABLE]
12340 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68   processing.  Th
12350 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20  e.** count does 
12360 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73  not include rows
12370 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66   of views that f
12380 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20  ire an [INSTEAD 
12390 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20  OF trigger],.** 
123a0 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e  though if the IN
123b0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
123c0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
123d0 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65  f its own, those
123e0 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65   changes .** are
123f0 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e   counted.)^.** ^
12400 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  The sqlite3_tota
12410 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  l_changes() func
12420 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20  tion counts the 
12430 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20  changes as soon 
12440 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  as.** the statem
12450 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
12460 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64  hem is completed
12470 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
12480 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69  ment handle.** i
12490 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
124a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
124b0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
124c0 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  ze()])..**.** Se
124d0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
124e0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
124f0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
12500 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
12510 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
12520 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
12530 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
12540 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
12550 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
12560 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
12570 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
12580 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
12590 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
125a0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
125b0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
125c0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
125d0 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
125e0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
125f0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  ingful..*/.int s
12600 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
12610 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
12620 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
12630 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
12640 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
12650 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
12660 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
12670 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
12680 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
12690 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
126a0 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
126b0 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
126c0 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
126d0 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
126e0 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
126f0 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
12700 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
12710 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
12720 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
12730 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
12740 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
12750 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
12760 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
12770 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
12780 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
12790 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
127a0 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
127b0 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
127c0 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
127d0 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
127e0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
127f0 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
12800 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
12810 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
12820 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
12830 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
12840 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
12850 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
12860 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
12870 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
12880 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
12890 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
128a0 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
128b0 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
128c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
128d0 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
128e0 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
128f0 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
12900 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
12910 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
12920 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
12930 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
12940 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
12950 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
12960 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
12970 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12980 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
12990 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
129a0 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
129b0 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
129c0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
129d0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
129e0 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
129f0 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
12a00 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
12a10 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
12a20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
12a30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
12a40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
12a50 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
12a60 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
12a70 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
12a80 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
12a90 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
12aa0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12ab0 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
12ac0 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
12ad0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
12ae0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
12af0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
12b00 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
12b10 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
12b20 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
12b30 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
12b40 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
12b50 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
12b60 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
12b70 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
12b80 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
12b90 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
12ba0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
12bb0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
12bc0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
12bd0 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
12be0 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
12bf0 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
12c00 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
12c10 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
12c20 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
12c30 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
12c40 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
12c50 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
12c60 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
12c70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
12c80 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
12c90 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
12ca0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
12cb0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
12cc0 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
12cd0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
12ce0 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
12cf0 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
12d00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
12d10 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
12d20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
12d30 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
12d40 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
12d50 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
12d60 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  en..*/.void sqli
12d70 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71  te3_interrupt(sq
12d80 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
12d90 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
12da0 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
12db0 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c  atement Is Compl
12dc0 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ete.**.** These 
12dd0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
12de0 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61  ful during comma
12df0 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f  nd-line input to
12e00 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68   determine if th
12e10 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65  e.** currently e
12e20 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d  ntered text seem
12e30 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70  s to form a comp
12e40 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
12e50 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69  nt or.** if addi
12e60 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20  tional input is 
12e70 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65  needed before se
12e80 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69  nding the text i
12e90 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f  nto.** SQLite fo
12ea0 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65  r parsing.  ^The
12eb0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
12ec0 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75  rn 1 if the inpu
12ed0 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65  t string.** appe
12ee0 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70  ars to be a comp
12ef0 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  lete SQL stateme
12f00 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e  nt.  ^A statemen
12f10 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62  t is judged to b
12f20 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66  e.** complete if
12f30 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20   it ends with a 
12f40 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20  semicolon token 
12f50 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65  and is not a pre
12f60 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c  fix of a.** well
12f70 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54  -formed CREATE T
12f80 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74  RIGGER statement
12f90 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74  .  ^Semicolons t
12fa0 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64  hat are embedded
12fb0 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e   within.** strin
12fc0 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75  g literals or qu
12fd0 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20  oted identifier 
12fe0 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74  names or comment
12ff0 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64  s are not.** ind
13000 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20  ependent tokens 
13010 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f  (they are part o
13020 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77  f the token in w
13030 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a  hich they are.**
13040 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74   embedded) and t
13050 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  hus do not count
13060 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20   as a statement 
13070 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68  terminator.  ^Wh
13080 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20  itespace.** and 
13090 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f  comments that fo
130a0 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73  llow the final s
130b0 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e  emicolon are ign
130c0 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ored..**.** ^The
130d0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
130e0 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74  rn 0 if the stat
130f0 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c  ement is incompl
13100 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d  ete.  ^If a.** m
13110 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13120 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c   fails, then SQL
13130 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74  ITE_NOMEM is ret
13140 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
13150 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20  ese routines do 
13160 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51  not parse the SQ
13170 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75  L statements thu
13180 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65  s.** will not de
13190 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c  tect syntactical
131a0 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c  ly incorrect SQL
131b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c  ..**.** ^(If SQL
131c0 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ite has not been
131d0 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69   initialized usi
131e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  ng [sqlite3_init
131f0 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20  ialize()] prior 
13200 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20  .** to invoking 
13210 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
13220 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65  16() then sqlite
13230 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
13240 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74  s invoked.** aut
13250 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
13260 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
13270 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69  ().  If that ini
13280 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c  tialization fail
13290 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72  s,.** then the r
132a0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
132b0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
132c0 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f  e16() will be no
132d0 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64  n-zero.** regard
132e0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
132f0 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74  or not the input
13300 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65   SQL is complete
13310 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  .)^.**.** The in
13320 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
13330 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74  complete()] must
13340 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
13350 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73  nated.** UTF-8 s
13360 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
13370 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
13380 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d  e3_complete16()]
13390 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
133a0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
133b0 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
133c0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
133d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
133e0 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
133f0 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20  char *sql);.int 
13400 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
13410 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  16(const void *s
13420 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ql);../*.** CAPI
13430 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41  3REF: Register A
13440 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e   Callback To Han
13450 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  dle SQLITE_BUSY 
13460 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  Errors.**.** ^Th
13470 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
13480 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
13490 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62  ion that might b
134a0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
134b0 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
134c0 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
134d0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
134e0 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74  e that another t
134f0 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63  hread.** or proc
13500 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a  ess has locked..
13510 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
13520 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
13530 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
13540 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
13550 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
13560 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
13570 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f   immediately upo
13580 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74  n encountering t
13590 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68  he lock.  ^If th
135a0 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a  e busy callback.
135b0 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  ** is not NULL, 
135c0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  then the callbac
135d0 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  k might be invok
135e0 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75  ed with two argu
135f0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
13600 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13610 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e   to the busy han
13620 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f  dler is a copy o
13630 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e  f the void* poin
13640 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
13650 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
13660 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75  nt to sqlite3_bu
13670 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e  sy_handler().  ^
13680 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
13690 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75  ent to.** the bu
136a0 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy handler callb
136b0 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ack is the numbe
136c0 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
136d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
136e0 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76   has.** been inv
136f0 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f  oked for this lo
13700 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
13710 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
13720 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
13730 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
13740 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
13750 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
13760 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
13770 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
13780 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
13790 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20  ERR_BLOCKED] is 
137a0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66  returned..** ^If
137b0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
137c0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
137d0 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
137e0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
137f0 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
13800 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67  base for reading
13810 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
13820 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
13830 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
13840 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
13850 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
13860 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
13870 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
13880 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
13890 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
138a0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
138b0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
138c0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
138d0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
138e0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
138f0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
13900 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
13910 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53  E_BUSY].** or [S
13920 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
13930 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20  KED] instead of 
13940 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
13950 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f  y handler..** Co
13960 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69  nsider a scenari
13970 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63  o where one proc
13980 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
13990 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a   read lock that.
139a0 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20  ** it is trying 
139b0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20  to promote to a 
139c0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e  reserved lock an
139d0 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72  d.** a second pr
139e0 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67  ocess is holding
139f0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
13a00 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69   that it is tryi
13a10 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ng.** to promote
13a20 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65   to an exclusive
13a30 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73   lock.  The firs
13a40 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  t process cannot
13a50 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61   proceed.** beca
13a60 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
13a70 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
13a80 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70  and the second p
13a90 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a  rocess cannot.**
13aa0 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65   proceed because
13ab0 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
13ac0 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66  y the first.  If
13ad0 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a   both processes.
13ae0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75  ** invoke the bu
13af0 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69  sy handlers, nei
13b00 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61  ther will make a
13b10 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68  ny progress.  Th
13b20 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69  erefore,.** SQLi
13b30 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  te returns [SQLI
13b40 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65  TE_BUSY] for the
13b50 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20   first process, 
13b60 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73  hoping that this
13b70 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20  .** will induce 
13b80 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
13b90 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73  s to release its
13ba0 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61   read lock and a
13bb0 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f  llow.** the seco
13bc0 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72  nd process to pr
13bd0 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oceed..**.** ^Th
13be0 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63  e default busy c
13bf0 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e  allback is NULL.
13c00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
13c10 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20  ITE_BUSY] error 
13c20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  is converted to 
13c30 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
13c40 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53  OCKED].** when S
13c50 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20  QLite is in the 
13c60 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67  middle of a larg
13c70 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68  e transaction wh
13c80 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63  ere all the.** c
13c90 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20  hanges will not 
13ca0 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d  fit into the in-
13cb0 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53  memory cache.  S
13cc0 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c  QLite will.** al
13cd0 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53  ready hold a RES
13ce0 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68  ERVED lock on th
13cf0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
13d00 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a   but it needs.**
13d10 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73   to promote this
13d20 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49   lock to EXCLUSI
13d30 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61  VE so that it ca
13d40 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a  n spill cache.**
13d50 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20   pages into the 
13d60 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
13d70 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f  thout harm to co
13d80 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64  ncurrent.** read
13d90 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20  ers.  ^If it is 
13da0 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74  unable to promot
13db0 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e  e the lock, then
13dc0 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a   the in-memory.*
13dd0 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20  * cache will be 
13de0 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e  left in an incon
13df0 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e  sistent state an
13e00 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a  d so the error.*
13e10 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74  * code is promot
13e20 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61  ed from the rela
13e30 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53  tively benign [S
13e40 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a  QLITE_BUSY] to.*
13e50 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72  * the more sever
13e60 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  e [SQLITE_IOERR_
13e70 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73  BLOCKED].  ^This
13e80 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d   error code prom
13e90 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20  otion.** forces 
13ea0 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c  an automatic rol
13eb0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61  lback of the cha
13ec0 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a  nges.  See the.*
13ed0 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74  * <a href="/cvst
13ee0 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75  rac/wiki?p=Corru
13ef0 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
13f00 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72  syError">.** Cor
13f10 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67  ruptionFollowing
13f20 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69  BusyError</a> wi
13f30 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69  ki page for a di
13f40 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a  scussion of why.
13f50 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72  ** this is impor
13f60 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  tant..**.** ^(Th
13f70 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
13f80 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
13f90 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
13fa0 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
13fb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
13fc0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
13fd0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
13fe0 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
13ff0 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
14000 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
14010 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
14020 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
14030 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73  ].** will also s
14040 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20  et or clear the 
14050 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
14060 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
14070 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
14080 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
14090 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
140a0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
140b0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
140c0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
140d0 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75  handler.  Any su
140e0 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
140f0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
14100 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
14110 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
14120 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
14130 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
14140 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
14150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14160 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
14170 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
14180 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
14190 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
141a0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
141b0 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
141c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
141d0 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
141e0 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
141f0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
14200 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
14210 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
14220 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
14230 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
14240 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
14250 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
14260 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
14270 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
14280 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
14290 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
142a0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
142b0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
142c0 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
142d0 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
142e0 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
142f0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
14300 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
14310 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
14320 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
14330 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
14340 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
14350 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
14360 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
14370 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
14380 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
14390 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
143a0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
143b0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
143c0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
143d0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
143e0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
143f0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
14400 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
14410 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
14420 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
14430 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
14440 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
14450 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
14460 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
14470 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
14480 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
14490 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
144a0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
144b0 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
144c0 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
144d0 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
144e0 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )^.*/.int sqlite
144f0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73  3_busy_timeout(s
14500 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29  qlite3*, int ms)
14510 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
14520 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52  F: Convenience R
14530 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e  outines For Runn
14540 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a  ing Queries.**.*
14550 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61  * This is a lega
14560 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  cy interface tha
14570 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66  t is preserved f
14580 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
14590 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55  patibility..** U
145a0 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  se of this inter
145b0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f  face is not reco
145c0 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44  mmended..**.** D
145d0 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e  efinition: A <b>
145e0 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e  result table</b>
145f0 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20   is memory data 
14600 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65  structure create
14610 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  d by the.** [sql
14620 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14630 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20  ] interface.  A 
14640 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63  result table rec
14650 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ords the.** comp
14660 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c  lete query resul
14670 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d  ts from one or m
14680 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a  ore queries..**.
14690 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e  ** The table con
146a0 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20  ceptually has a 
146b0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61  number of rows a
146c0 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74  nd columns.  But
146d0 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72  .** these number
146e0 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f  s are not part o
146f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
14700 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73  le itself.  Thes
14710 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65  e.** numbers are
14720 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61   obtained separa
14730 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20  tely.  Let N be 
14740 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
14750 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74  ws.** and M be t
14760 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
14770 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  umns..**.** A re
14780 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e  sult table is an
14790 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
147a0 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  rs to zero-termi
147b0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
147c0 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ngs..** There ar
147d0 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e  e (N+1)*M elemen
147e0 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e  ts in the array.
147f0 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f    The first M po
14800 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20  inters point.** 
14810 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
14820 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20  ed strings that 
14830 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d   contain the nam
14840 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  es of the column
14850 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e  s..** The remain
14860 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20  ing entries all 
14870 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72  point to query r
14880 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61  esults.  NULL va
14890 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69  lues result.** i
148a0 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e  n NULL pointers.
148b0 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75    All other valu
148c0 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20  es are in their 
148d0 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69  UTF-8 zero-termi
148e0 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20  nated.** string 
148f0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61  representation a
14900 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
14910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
14920 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  xt()]..**.** A r
14930 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68  esult table migh
14940 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65  t consist of one
14950 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20   or more memory 
14960 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20  allocations..** 
14970 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
14980 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20  o pass a result 
14990 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74  table directly t
149a0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
149b0 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  )]..** A result 
149c0 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  table should be 
149d0 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e  deallocated usin
149e0 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  g [sqlite3_free_
149f0 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  table()]..**.** 
14a00 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  ^(As an example 
14a10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
14a20 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70  ble format, supp
14a30 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75  ose a query resu
14a40 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c  lt.** is as foll
14a50 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
14a60 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
14a70 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20         Name     
14a80 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20     | Age.**     
14a90 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d     -------------
14aa0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20  ----------.**   
14ab0 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20       Alice      
14ac0 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20   | 43.**        
14ad0 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38  Bob         | 28
14ae0 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79  .**        Cindy
14af0 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c         | 21.** <
14b00 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
14b10 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61  e>.**.** There a
14b20 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d  re two column (M
14b30 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72  ==2) and three r
14b40 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75  ows (N==3).  Thu
14b50 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  s the.** result 
14b60 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72  table has 8 entr
14b70 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68  ies.  Suppose th
14b80 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  e result table i
14b90 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61  s stored.** in a
14ba0 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a  n array names az
14bb0 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a  Result.  Then az
14bc0 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69  Result holds thi
14bd0 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a  s content:.**.**
14be0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
14bf0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  e>.**        azR
14c00 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22  esult&#91;0] = "
14c10 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  Name";.**       
14c20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d   azResult&#91;1]
14c30 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20   = "Age";.**    
14c40 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
14c50 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a  ;2] = "Alice";.*
14c60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
14c70 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b  t&#91;3] = "43";
14c80 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
14c90 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f  ult&#91;4] = "Bo
14ca0 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  b";.**        az
14cb0 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20  Result&#91;5] = 
14cc0 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "28";.**        
14cd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20  azResult&#91;6] 
14ce0 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20  = "Cindy";.**   
14cf0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
14d00 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20  1;7] = "21";.** 
14d10 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
14d20 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
14d30 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
14d40 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76  le() function ev
14d50 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d  aluates one or m
14d60 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ore.** semicolon
14d70 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73  -separated SQL s
14d80 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
14d90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
14da0 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67   UTF-8.** string
14db0 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61   of its 2nd para
14dc0 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e  meter and return
14dd0 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
14de0 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74   to the.** point
14df0 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20  er given in its 
14e00 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  3rd parameter..*
14e10 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61  *.** After the a
14e20 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66  pplication has f
14e30 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65  inished with the
14e40 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c   result from sql
14e50 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
14e60 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73  ,.** it must pas
14e70 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  s the result tab
14e80 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  le pointer to sq
14e90 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
14ea0 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a  () in order to.*
14eb0 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  * release the me
14ec0 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61  mory that was ma
14ed0 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65  lloced.  Because
14ee0 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a   of the way the.
14ef0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
14f00 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69  oc()] happens wi
14f10 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74  thin sqlite3_get
14f20 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61  _table(), the ca
14f30 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  lling.** functio
14f40 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74  n must not try t
14f50 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  o call [sqlite3_
14f60 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79  free()] directly
14f70 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69  .  Only.** [sqli
14f80 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
14f90 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c  ] is able to rel
14fa0 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
14fb0 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66  properly and saf
14fc0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ely..**.** The s
14fd0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
14fe0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
14ff0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61  implemented as a
15000 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
15010 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
15020 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ()].  The sqlite
15030 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f  3_get_table() ro
15040 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68  utine does not h
15050 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ave access.** to
15060 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61   any internal da
15070 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66  ta structures of
15080 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65   SQLite.  It use
15090 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69  s only the publi
150a0 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64  c.** interface d
150b0 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73  efined here.  As
150c0 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20   a consequence, 
150d0 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75  errors that occu
150e0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70  r in the.** wrap
150f0 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64  per layer outsid
15100 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61  e of the interna
15110 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  l [sqlite3_exec(
15120 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a  )] call are not.
15130 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20  ** reflected in 
15140 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
15150 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
15160 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  code()] or.** [s
15170 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
15180 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
15190 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
151a0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
151b0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
151c0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
151d0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
151e0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
151f0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
15200 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
15210 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
15220 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
15230 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
15240 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
15250 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
15260 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
15270 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
15280 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
15290 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
152a0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
152b0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
152c0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
152d0 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
152e0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f 69  n here */.);.voi
152f0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
15300 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
15310 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
15320 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
15330 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
15340 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
15350 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
15360 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
15370 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
15380 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
15390 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
153a0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
153b0 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ary..**.** ^The 
153c0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
153d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
153e0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
153f0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
15400 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
15410 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
15420 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
15430 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
15440 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
15450 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
15460 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
15470 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
15480 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
15490 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
154a0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
154b0 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
154c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
154d0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
154e0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
154f0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
15500 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
15510 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 73  ng..**.** ^(In s
15520 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
15530 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d  ) routine is sim
15540 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74  ilar to "snprint
15550 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  f()" from.** the
15560 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
15570 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ary.  The result
15580 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
15590 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73   the.** buffer s
155a0 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73  upplied as the s
155b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
155c0 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69  whose size is gi
155d0 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69  ven by.** the fi
155e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e  rst parameter. N
155f0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64  ote that the ord
15600 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72  er of the.** fir
15610 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72  st two parameter
15620 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72  s is reversed fr
15630 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e  om snprintf().)^
15640 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20    This is an.** 
15650 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64  historical accid
15660 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20  ent that cannot 
15670 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74  be fixed without
15680 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63   breaking.** bac
15690 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
156a0 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c  lity.  ^(Note al
156b0 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  so that sqlite3_
156c0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65  snprintf().** re
156d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
156e0 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e  to its buffer in
156f0 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d  stead of the num
15700 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63  ber of.** charac
15710 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72  ters actually wr
15720 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62  itten into the b
15730 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d  uffer.)^  We adm
15740 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e  it that.** the n
15750 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
15760 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c  ers written woul
15770 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66  d be a more usef
15780 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  ul return.** val
15790 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74  ue but we cannot
157a0 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c   change the impl
157b0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
157c0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
157d0 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20  .** now without 
157e0 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69  breaking compati
157f0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
15800 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75  s long as the bu
15810 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65  ffer size is gre
15820 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20  ater than zero, 
15830 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
15840 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73  ().** guarantees
15850 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72   that the buffer
15860 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d   is always zero-
15870 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
15880 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
15890 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20  eter "n" is the 
158a0 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68  total size of th
158b0 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64  e buffer, includ
158c0 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a  ing space for.**
158d0 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
158e0 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f  ator.  So the lo
158f0 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61  ngest string tha
15900 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74  t can be complet
15910 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77  ely.** written w
15920 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61  ill be n-1 chara
15930 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  cters..**.** The
15940 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
15950 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
15960 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
15970 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
15980 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
15990 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
159a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
159b0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
159c0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
159d0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
159e0 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
159f0 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
15a00 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
15a10 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  , and "%z" optio
15a20 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
15a30 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
15a40 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
15a50 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
15a60 20 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64   null-terminated
15a70 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
15a80 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
15a90 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
15aa0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
15ab0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
15ac0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
15ad0 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
15ae0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
15af0 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
15b00 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
15b10 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
15b20 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
15b30 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
15b40 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
15b50 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
15b60 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
15b70 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
15b80 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
15b90 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
15ba0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
15bb0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15bc0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
15bd0 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
15be0 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
15bf0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
15c00 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
15c10 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
15c20 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
15c30 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
15c40 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
15c50 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
15c60 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
15c70 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
15c80 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
15c90 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
15ca0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
15cb0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
15cc0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
15cd0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
15ce0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
15cf0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
15d00 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
15d10 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
15d20 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
15d30 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
15d40 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
15d50 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
15d60 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
15d70 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
15d80 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
15d90 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
15da0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
15db0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
15dc0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
15dd0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
15de0 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
15df0 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
15e00 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
15e10 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
15e20 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
15e30 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
15e40 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
15e50 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
15e60 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
15e70 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
15e80 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
15e90 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
15ea0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
15eb0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
15ec0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
15ed0 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
15ee0 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
15ef0 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
15f00 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
15f10 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
15f20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
15f30 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
15f40 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
15f50 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
15f60 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
15f70 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
15f80 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
15f90 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
15fa0 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
15fb0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
15fc0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
15fd0 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
15fe0 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
15ff0 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
16000 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
16010 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
16020 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
16030 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
16040 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
16050 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
16060 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
16070 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
16080 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
16090 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
160a0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
160b0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
160c0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
160d0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
160e0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
160f0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
16100 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
16110 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
16120 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
16130 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
16140 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
16150 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
16160 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
16170 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
16180 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
16190 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
161a0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
161b0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
161c0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
161d0 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
161e0 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
161f0 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
16200 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
16210 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
16220 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
16230 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
16240 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68   string.)^.*/.ch
16250 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69  ar *sqlite3_mpri
16260 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
16270 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
16280 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
16290 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
162a0 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  t);.char *sqlite
162b0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
162c0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
162d0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
162e0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
162f0 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
16300 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
16310 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
16320 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
16330 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
16340 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
16350 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
16360 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
16370 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
16380 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
16390 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
163a0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
163b0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
163c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
163d0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
163e0 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
163f0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
16400 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
16410 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
16420 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
16430 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
16440 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
16450 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
16460 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
16470 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
16480 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
16490 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
164a0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
164b0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
164c0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
164d0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
164e0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
164f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
16500 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
16510 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
16520 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
16530 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
16540 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
16550 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
16560 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
16570 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
16580 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
16590 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
165a0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
165b0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
165c0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
165d0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
165e0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
165f0 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
16600 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
16610 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
16620 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
16630 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
16640 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
16650 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
16660 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
16670 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
16680 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
16690 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
166a0 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
166b0 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
166c0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
166d0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
166e0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
166f0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
16700 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
16710 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
16720 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
16730 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
16740 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
16750 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
16760 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
16770 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
16780 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
16790 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
167a0 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
167b0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
167c0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
167d0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
167e0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
167f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
16800 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
16810 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  (The sqlite3_rea
16820 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
16830 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
16840 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
16850 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16860 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
16870 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
16880 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
16890 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
168a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
168b0 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
168c0 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
168d0 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e  * parameter.)^ ^
168e0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
168f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
16900 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
16910 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
16920 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
16930 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
16940 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
16950 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
16960 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
16970 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16980 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
16990 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  loc()..** ^If th
169a0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
169b0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
169c0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
169d0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
169e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
169f0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
16a00 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
16a10 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
16a20 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68  P) where P is th
16a30 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
16a40 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
16a50 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69  lloc()..** ^sqli
16a60 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
16a70 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
16a80 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
16a90 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
16aa0 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
16ab0 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
16ac0 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
16ad0 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
16ae0 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
16af0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
16b00 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
16b10 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
16b20 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
16b30 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
16b40 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
16b50 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
16b60 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
16b70 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
16b80 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
16b90 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
16ba0 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
16bb0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
16bc0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
16bd0 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
16be0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
16bf0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
16c00 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
16c10 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
16c20 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
16c30 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
16c40 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
16c50 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
16c60 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
16c70 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a  undary, or to a.
16c80 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61  ** 4 byte bounda
16c90 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ry if the [SQLIT
16ca0 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44  E_4_BYTE_ALIGNED
16cb0 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65  _MALLOC] compile
16cc0 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
16cd0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
16ce0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
16cf0 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
16d00 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
16d10 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
16d20 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
16d30 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
16d40 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
16d50 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
16d60 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
16d70 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
16d80 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
16d90 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
16da0 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
16db0 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
16dc0 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
16dd0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
16de0 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
16df0 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
16e00 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
16e10 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
16e20 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
16e30 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
16e40 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
16e50 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
16e60 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
16e70 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
16e80 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
16e90 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
16ea0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
16eb0 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
16ec0 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
16ed0 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
16ee0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16ef0 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
16f00 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
16f10 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
16f20 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
16f30 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
16f40 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
16f50 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
16f60 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
16f70 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
16f80 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
16f90 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
16fa0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
16fb0 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
16fc0 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
16fd0 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
16fe0 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
16ff0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
17000 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
17010 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17020 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
17030 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
17040 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
17050 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
17060 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
17070 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
17080 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
17090 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
170a0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
170b0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
170c0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
170d0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
170e0 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
170f0 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
17100 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
17110 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
17120 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
17130 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
17140 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
17150 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
17160 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
17170 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
17180 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
17190 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
171a0 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
171b0 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
171c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
171d0 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
171e0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
171f0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
17200 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
17210 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
17220 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
17230 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
17240 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
17250 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
17260 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
17270 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
17280 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
17290 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
172a0 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
172b0 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
172c0 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
172d0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
172e0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
172f0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
17300 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
17310 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
17320 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
17330 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
17340 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
17350 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
17360 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
17370 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
17380 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
17390 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
173a0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
173b0 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
173c0 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
173d0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
173e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
173f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17400 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
17410 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
17420 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
17430 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
17440 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
17450 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
17460 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
17470 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
17480 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
17490 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
174a0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
174b0 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
174c0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
174d0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
174e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
174f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
17500 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
17510 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
17520 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
17530 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
17540 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
17550 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
17560 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
17570 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
17580 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
17590 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
175a0 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
175b0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
175c0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
175d0 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
175e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
175f0 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
17600 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
17610 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
17620 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
17630 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
17640 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
17650 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
17660 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
17670 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
17680 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
17690 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
176a0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
176b0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
176c0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
176d0 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
176e0 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
176f0 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
17700 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
17710 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
17720 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
17730 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
17740 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
17750 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
17760 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
17770 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
17780 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
17790 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
177a0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
177b0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
177c0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
177d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
177e0 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
177f0 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
17800 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
17810 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
17820 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
17830 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
17840 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
17850 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
17860 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
17870 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
17880 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
17890 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
178a0 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
178b0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
178c0 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
178d0 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
178e0 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
178f0 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
17900 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
17910 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
17920 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
17930 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
17940 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
17950 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
17960 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17970 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
17980 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
17990 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
179a0 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
179b0 72 73 20 61 20 61 75 74 68 6f 72 69 7a 65 72 20  rs a authorizer 
179c0 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20  callback with a 
179d0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
179e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
179f0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e  on], supplied in
17a00 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
17a10 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74  ent..** ^The aut
17a20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
17a30 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53   is invoked as S
17a40 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
17a50 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64  e being compiled
17a60 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
17a70 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
17a80 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69  s variants [sqli
17a90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17aa0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ],.** [sqlite3_p
17ab0 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20  repare16()] and 
17ac0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
17ad0 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76  16_v2()].  ^At v
17ae0 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73  arious.** points
17af0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70   during the comp
17b00 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c  ilation process,
17b10 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69   as logic is bei
17b20 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f  ng created.** to
17b30 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
17b40 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75   actions, the au
17b50 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
17b60 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a  k is invoked to.
17b70 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20  ** see if those 
17b80 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f  actions are allo
17b90 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f  wed.  ^The autho
17ba0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73  rizer callback s
17bb0 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
17bc0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61  [SQLITE_OK] to a
17bd0 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c  llow the action,
17be0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
17bf0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65   to disallow the
17c00 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74  .** specific act
17c10 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68  ion but allow th
17c20 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
17c30 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  to continue to b
17c40 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f  e.** compiled, o
17c50 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20  r [SQLITE_DENY] 
17c60 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74  to cause the ent
17c70 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ire SQL statemen
17c80 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63  t to be.** rejec
17c90 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ted with an erro
17ca0 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68  r.  ^If the auth
17cb0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
17cc0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76  returns.** any v
17cd0 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
17ce0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c  [SQLITE_IGNORE],
17cf0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72   [SQLITE_OK], or
17d00 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a   [SQLITE_DENY].*
17d10 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69  * then the [sqli
17d20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
17d30 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
17d40 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
17d50 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  red.** the autho
17d60 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
17d70 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
17d80 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ssage..**.** Whe
17d90 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  n the callback r
17da0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
17db0 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  K], that means t
17dc0 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
17dd0 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e  requested is ok.
17de0 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c    ^When the call
17df0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
17e00 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a  LITE_DENY], the.
17e10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
17e20 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
17e30 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
17e40 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a  t triggered the.
17e50 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  ** authorizer wi
17e60 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
17e70 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78  error message ex
17e80 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a  plaining that.**
17e90 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65   access is denie
17ea0 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  d. .**.** ^The f
17eb0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
17ec0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
17ed0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63   callback is a c
17ee0 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64  opy of the third
17ef0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
17f00 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
17f10 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e  _authorizer() in
17f20 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65  terface. ^The se
17f30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a  cond parameter.*
17f40 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
17f50 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
17f60 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61  [SQLITE_COPY | a
17f70 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74  ction code] that
17f80 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68   specifies.** th
17f90 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74  e particular act
17fa0 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
17fb0 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64  ized. ^The third
17fc0 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70   through sixth p
17fd0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
17fe0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65  the callback are
17ff0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
18000 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f   strings that co
18010 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c  ntain additional
18020 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75  .** details abou
18030 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20  t the action to 
18040 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a  be authorized..*
18050 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  *.** ^If the act
18060 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
18070 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64  ITE_READ].** and
18080 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
18090 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47  turns [SQLITE_IG
180a0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a  NORE] then the.*
180b0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
180c0 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74  ement] statement
180d0 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20   is constructed 
180e0 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a  to substitute.**
180f0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e   a NULL value in
18100 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61   place of the ta
18110 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
18120 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65  would have.** be
18130 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49  en read if [SQLI
18140 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20  TE_OK] had been 
18150 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b  returned.  The [
18160 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a  SQLITE_IGNORE].*
18170 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20  * return can be 
18180 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20  used to deny an 
18190 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61  untrusted user a
181a0 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64  ccess to individ
181b0 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f  ual.** columns o
181c0 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49  f a table..** ^I
181d0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
181e0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
181f0 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
18200 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
18210 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
18220 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
18230 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
18240 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
18250 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
18260 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
18270 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
18280 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
18290 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
182a0 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
182b0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
182c0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
182d0 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
182e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
182f0 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
18300 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
18310 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
18320 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
18330 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
18340 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
18350 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
18360 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
18370 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
18380 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
18390 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
183a0 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
183b0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
183c0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
183d0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
183e0 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
183f0 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
18400 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
18410 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
18420 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
18430 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
18440 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
18450 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
18460 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
18470 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
18480 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
18490 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
184a0 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
184b0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
184c0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
184d0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
184e0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
184f0 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
18500 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
18510 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
18520 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
18530 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
18540 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
18550 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
18560 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
18570 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
18580 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
18590 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
185a0 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
185b0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
185c0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
185d0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
185e0 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
185f0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
18600 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
18610 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
18620 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
18630 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
18640 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
18650 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
18660 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
18670 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
18680 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
18690 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
186a0 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
186b0 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
186c0 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
186d0 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
186e0 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
186f0 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
18700 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
18710 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
18720 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
18730 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
18740 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
18750 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
18760 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
18770 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
18780 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
18790 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
187a0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
187b0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
187c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
187d0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
187e0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
187f0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
18800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18810 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
18820 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
18830 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
18840 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
18850 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18860 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
18870 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
18880 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
18890 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
188a0 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
188b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
188c0 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
188d0 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
188e0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
188f0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
18900 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
18910 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
18920 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
18930 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
18940 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
18950 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
18960 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
18970 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18980 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
18990 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
189a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
189b0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
189c0 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
189d0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
189e0 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
189f0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
18a00 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
18a10 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
18a20 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
18a30 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
18a40 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
18a50 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
18a60 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
18a70 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
18a80 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
18a90 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
18aa0 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  hange..*/.int sq
18ab0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18ac0 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
18ad0 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
18ae0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
18af0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
18b00 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
18b10 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
18b20 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
18b30 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18b40 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
18b50 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
18b60 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
18b70 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
18b80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
18b90 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
18ba0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
18bb0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
18bc0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
18bd0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
18be0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
18bf0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
18c00 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
18c10 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
18c20 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
18c30 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
18c40 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
18c50 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
18c60 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
18c70 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
18c80 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
18c90 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
18ca0 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
18cb0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
18cc0 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
18cd0 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
18ce0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
18cf0 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
18d00 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
18d10 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
18d20 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
18d30 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
18d40 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
18d50 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
18d60 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
18d70 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
18d80 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
18d90 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
18da0 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
18db0 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
18dc0 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
18dd0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
18de0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
18df0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
18e00 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
18e10 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
18e20 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
18e30 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
18e40 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
18e50 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
18e60 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
18e70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
18e80 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
18e90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
18ea0 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
18eb0 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
18ec0 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
18ed0 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
18ee0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
18ef0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
18f00 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
18f10 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
18f20 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
18f30 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
18f40 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
18f50 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
18f60 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
18f70 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
18f80 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
18f90 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
18fa0 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
18fb0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
18fc0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
18fd0 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
18fe0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
18ff0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
19000 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
19010 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
19020 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19030 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
19040 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
19050 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
19060 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
19070 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
19080 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
19090 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
190a0 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
190b0 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
190c0 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
190d0 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
190e0 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
190f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19100 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
19110 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
19120 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
19130 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19140 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
19150 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
19160 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
19170 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
19180 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19190 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
191a0 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
191b0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
191c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
191d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
191e0 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
191f0 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
19200 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
19210 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
19220 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
19230 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
19240 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
19250 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
19260 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
19270 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19280 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
19290 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
192a0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
192b0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
192c0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
192d0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
192e0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
192f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
19300 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19310 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
19320 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
19330 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
19340 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
19350 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19360 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
19370 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
19380 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
19390 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
193a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
193b0 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
193c0 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
193d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
193e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
193f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19400 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
19410 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
19420 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
19430 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19440 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19450 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
19460 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
19470 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19480 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19490 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
194a0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
194b0 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
194c0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
194d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
194e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
194f0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
19500 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
19510 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
19520 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
19530 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19540 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
19550 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
19560 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
19570 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
19580 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19590 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
195a0 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
195b0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
195c0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
195d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
195e0 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
195f0 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
19600 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
19610 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
19620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
19630 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
19640 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
19650 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
19660 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19670 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
19680 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
19690 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
196a0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
196b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
196c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
196d0 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
196e0 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
196f0 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
19700 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
19710 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
19720 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
19730 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
19740 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
19750 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
19760 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
19770 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
19780 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
19790 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
197a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
197b0 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
197c0 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
197d0 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
197e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
197f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19800 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
19810 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
19820 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
19830 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
19840 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19850 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
19860 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
19870 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
19880 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19890 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
198a0 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
198b0 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
198c0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
198d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
198e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
198f0 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
19900 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
19910 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
19920 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
19930 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19940 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
19950 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
19960 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
19970 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
19980 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19990 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
199a0 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
199b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
199c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
199d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
199e0 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
199f0 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
19a00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
19a10 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
19a20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19a30 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
19a40 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
19a50 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
19a60 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
19a70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19a80 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
19a90 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
19aa0 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
19ab0 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
19ac0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
19ad0 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
19ae0 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
19af0 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
19b00 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
19b10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
19b20 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
19b30 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
19b40 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
19b50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
19b60 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
19b70 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
19b80 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
19b90 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
19ba0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
19bb0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
19bc0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
19bd0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
19be0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
19bf0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
19c00 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
19c10 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
19c20 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
19c30 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
19c40 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
19c50 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
19c60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
19c70 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
19c80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
19c90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19ca0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
19cb0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
19cc0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
19cd0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
19ce0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
19cf0 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
19d00 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
19d10 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
19d20 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
19d30 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
19d40 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
19d50 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
19d60 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
19d70 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
19d80 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
19d90 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
19da0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
19db0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
19dc0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
19dd0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r.)^.**.** ^The 
19de0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
19df0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
19e00 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
19e10 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
19e20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  as each SQL stat
19e30 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20  ement finishes. 
19e40 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61   ^The profile ca
19e50 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a  llback contains.
19e60 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
19e70 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
19e80 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  nd an estimate o
19e90 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d  f wall-clock tim
19ea0 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67  e.** of how long
19eb0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
19ec0 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54  took to run.  ^T
19ed0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
19ee0 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69  ack.** time is i
19ef0 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73  n units of nanos
19f00 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20  econds, however 
19f10 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
19f20 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73  ementation.** is
19f30 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66   only capable of
19f40 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73   millisecond res
19f50 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73  olution so the s
19f60 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69  ix least signifi
19f70 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69  cant.** digits i
19f80 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d  n the time are m
19f90 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74  eaningless.  Fut
19fa0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
19fb0 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20  SQLite.** might 
19fc0 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20  provide greater 
19fd0 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68  resolution on th
19fe0 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62  e profiler callb
19ff0 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c  ack.  The.** sql
1a000 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66  ite3_profile() f
1a010 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69  unction is consi
1a020 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74  dered experiment
1a030 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62  al and is.** sub
1a040 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69  ject to change i
1a050 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
1a060 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  s of SQLite..*/.
1a070 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
1a080 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
1a090 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
1a0a0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
1a0b0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45  void*);.SQLITE_E
1a0c0 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
1a0d0 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
1a0e0 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
1a0f0 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
1a100 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1a110 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
1a120 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1a130 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
1a140 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
1a150 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
1a160 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1a170 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
1a180 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
1a190 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
1a1a0 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
1a1b0 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
1a1c0 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
1a1d0 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
1a1e0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
1a1f0 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
1a200 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
1a210 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1a220 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
1a230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1a240 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
1a250 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
1a260 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
1a270 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
1a280 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
1a290 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
1a2a0 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
1a2b0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
1a2c0 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
1a2d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
1a2e0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1a2f0 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
1a300 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
1a310 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
1a320 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
1a330 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
1a340 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
1a350 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
1a360 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
1a370 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
1a380 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  k X..**.** ^Only
1a390 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
1a3a0 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
1a3b0 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
1a3c0 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
1a3d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a3e0 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
1a3f0 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
1a400 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
1a410 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
1a420 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
1a430 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
1a440 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
1a450 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
1a460 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1a470 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
1a480 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
1a490 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
1a4a0 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
1a4b0 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
1a4c0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1a4d0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1a4e0 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1a4f0 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1a500 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1a510 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1a520 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1a530 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1a540 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1a550 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1a560 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1a570 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1a580 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1a590 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1a5a0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1a5b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1a5c0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
1a5d0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1a5e0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1a5f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1a600 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1a610 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1a620 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1a630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a640 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1a650 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1a660 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1a670 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
1a680 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1a690 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1a6a0 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
1a6b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
1a6c0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
1a6d0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
1a6e0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
1a6f0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1a700 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69  nes open an SQLi
1a710 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  te database file
1a720 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73 20 67   whose name is g
1a730 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a 20 66  iven by the.** f
1a740 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1a750 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
1a760 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
1a770 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
1a780 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1a790 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1a7a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
1a7b0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
1a7c0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
1a7d0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
1a7e0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
1a7f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a800 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
1a810 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
1a820 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
1a830 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
1a840 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
1a850 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
1a860 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
1a870 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1a880 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
1a890 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
1a8a0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
1a8b0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
1a8c0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
1a8d0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
1a8e0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1a8f0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
1a900 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
1a910 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1a920 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
1a930 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
1a940 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
1a950 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
1a960 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
1a970 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1a980 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
1a990 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1a9a0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
1a9b0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
1a9c0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
1a9d0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
1a9e0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
1a9f0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
1aa00 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
1aa10 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
1aa20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
1aa30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1aa40 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
1aa50 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
1aa60 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
1aa70 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
1aa80 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
1aa90 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
1aaa0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1aab0 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
1aac0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1aad0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1aae0 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
1aaf0 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
1ab00 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
1ab10 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
1ab20 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
1ab30 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
1ab40 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1ab50 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1ab60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1ab70 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
1ab80 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
1ab90 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
1aba0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
1abb0 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
1abc0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1abd0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
1abe0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
1abf0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
1ac00 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
1ac10 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
1ac20 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
1ac30 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
1ac40 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
1ac50 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
1ac60 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1ac70 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
1ac80 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
1ac90 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
1aca0 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
1acb0 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
1acc0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
1acd0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
1ace0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1acf0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
1ad00 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
1ad10 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1ad20 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
1ad30 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1ad40 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  HE],.** and/or [
1ad50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
1ad60 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 3a  ATECACHE] flags:
1ad70 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
1ad80 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1ad90 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
1ada0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
1adb0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
1adc0 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
1add0 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
1ade0 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
1adf0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
1ae00 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
1ae10 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
1ae20 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1ae30 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
1ae40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1ae50 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1ae60 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
1ae70 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
1ae80 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
1ae90 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
1aea0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
1aeb0 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
1aec0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1aed0 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
1aee0 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
1aef0 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
1af00 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
1af10 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
1af20 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1af30 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1af40 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1af50 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
1af60 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
1af70 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1af80 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
1af90 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
1afa0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
1afb0 61 74 65 73 20 69 74 20 69 66 0a 2a 2a 20 69 74  ates it if.** it
1afc0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1afd0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1afe0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1aff0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1b000 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1b010 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1b020 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1b030 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
1b040 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1b050 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1b060 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1b070 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1b080 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1b090 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
1b0a0 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
1b0b0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1b0c0 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
1b0d0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
1b0e0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
1b0f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1b100 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  MUTEX],.** [SQLI
1b110 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1b120 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  CHE] and/or [SQL
1b130 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1b140 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a  CACHE] flags,.**
1b150 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1b160 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1b170 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
1b180 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1b190 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1b1a0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1b1b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1b1c0 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
1b1d0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
1b1e0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
1b1f0 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
1b200 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
1b210 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
1b220 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1b230 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1b240 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
1b250 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1b260 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1b270 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1b280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1b290 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1b2a0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1b2b0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1b2c0 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1b2d0 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1b2e0 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1b2f0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1b300 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
1b310 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
1b320 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
1b330 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
1b340 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b350 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
1b360 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
1b370 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
1b380 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1b390 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1b3a0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
1b3b0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
1b3c0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1b3d0 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
1b3e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1b3f0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1b400 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1b410 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b420 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
1b430 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
1b440 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1b450 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
1b460 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
1b470 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1b480 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1b490 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1b4a0 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1b4b0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1b4c0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1b4d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1b4e0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1b4f0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1b500 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1b510 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b520 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1b530 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1b540 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1b550 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1b560 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1b570 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1b580 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1b590 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1b5a0 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1b5b0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1b5c0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1b5d0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1b5e0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1b5f0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1b600 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1b610 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1b620 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1b630 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1b640 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1b650 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1b660 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
1b670 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1b680 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1b690 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
1b6a0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1b6b0 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
1b6c0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
1b6d0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
1b6e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
1b6f0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
1b700 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1b710 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1b720 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
1b730 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1b740 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1b750 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
1b760 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1b770 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
1b780 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
1b790 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1b7a0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
1b7b0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
1b7c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
1b7d0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
1b7e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1b7f0 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1b800 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1b810 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1b820 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1b830 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
1b840 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
1b850 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
1b860 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
1b870 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
1b880 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
1b890 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1b8a0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1b8b0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
1b8c0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
1b8d0 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
1b8e0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
1b8f0 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
1b900 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
1b910 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
1b920 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
1b930 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
1b940 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
1b950 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
1b960 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1b970 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b980 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1b990 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
1b9a0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1b9b0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1b9c0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1b9d0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1b9e0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
1b9f0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1ba00 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
1ba10 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
1ba20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
1ba30 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
1ba40 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
1ba50 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
1ba60 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
1ba70 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
1ba80 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
1ba90 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
1baa0 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
1bab0 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1bac0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1bad0 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1bae0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1baf0 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
1bb00 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1bb10 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
1bb20 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
1bb30 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
1bb40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
1bb50 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
1bb60 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
1bb70 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
1bb80 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
1bb90 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
1bba0 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
1bbb0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1bbc0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1bbd0 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
1bbe0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
1bbf0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1bc00 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
1bc10 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
1bc20 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
1bc30 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
1bc40 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
1bc50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1bc60 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
1bc70 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
1bc80 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
1bc90 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
1bca0 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
1bcb0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
1bcc0 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
1bcd0 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
1bce0 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1bcf0 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1bd00 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
1bd10 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
1bd20 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
1bd30 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
1bd40 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1bd50 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
1bd60 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
1bd70 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
1bd80 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
1bd90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
1bda0 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
1bdb0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
1bdc0 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1bdd0 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
1bde0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
1bdf0 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
1be00 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1be10 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1be20 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
1be30 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
1be40 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
1be50 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
1be60 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
1be70 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
1be80 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
1be90 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
1bea0 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
1beb0 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
1bec0 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
1bed0 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
1bee0 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
1bef0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1bf00 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
1bf10 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
1bf20 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65  ons.)^.**.** Whe
1bf30 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
1bf40 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1bf50 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
1bf60 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
1bf70 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
1bf80 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
1bf90 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
1bfa0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
1bfb0 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
1bfc0 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
1bfd0 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
1bfe0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
1bff0 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
1c000 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
1c010 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
1c020 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
1c030 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
1c040 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
1c050 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1c060 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
1c070 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
1c080 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
1c090 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
1c0a0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
1c0b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
1c0c0 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
1c0d0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
1c0e0 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
1c0f0 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
1c100 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
1c110 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
1c120 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
1c130 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
1c140 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
1c150 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
1c160 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
1c170 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
1c180 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
1c190 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
1c1a0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
1c1b0 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
1c1c0 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
1c1d0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
1c1e0 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
1c1f0 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
1c200 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
1c210 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
1c220 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
1c230 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
1c240 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
1c250 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
1c260 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
1c270 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
1c280 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
1c290 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
1c2a0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1c2b0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
1c2c0 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
1c2d0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
1c2e0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  6(sqlite3*);../*
1c2f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
1c300 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
1c310 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
1c320 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
1c330 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
1c340 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
1c350 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
1c360 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
1c370 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
1c380 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1c390 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
1c3a0 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
1c3b0 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
1c3c0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
1c3d0 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
1c3e0 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
1c3f0 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
1c400 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
1c410 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
1c420 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
1c430 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
1c440 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
1c450 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
1c460 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1c470 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
1c480 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
1c490 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
1c4a0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
1c4b0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
1c4c0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
1c4d0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
1c4e0 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
1c4f0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
1c500 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
1c510 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
1c520 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c530 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
1c540 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
1c550 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
1c560 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
1c570 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
1c580 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
1c590 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
1c5a0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
1c5b0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
1c5c0 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
1c5d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
1c5e0 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
1c5f0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
1c600 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
1c610 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
1c620 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
1c630 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1c640 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
1c650 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
1c660 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
1c670 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
1c680 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
1c690 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
1c6a0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
1c6b0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
1c6c0 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
1c6d0 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
1c6e0 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
1c6f0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
1c700 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
1c710 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1c720 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
1c730 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c740 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
1c750 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
1c760 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
1c770 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1c780 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
1c790 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
1c7a0 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
1c7b0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
1c7c0 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
1c7d0 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
1c7e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
1c7f0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
1c800 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
1c810 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
1c820 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
1c830 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
1c840 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
1c850 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
1c860 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
1c870 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
1c880 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
1c890 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
1c8a0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
1c8b0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
1c8c0 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
1c8d0 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
1c8e0 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
1c8f0 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
1c900 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
1c910 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
1c920 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
1c930 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
1c940 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
1c950 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
1c960 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
1c970 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
1c980 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
1c990 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
1c9a0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
1c9b0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
1c9c0 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
1c9d0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
1c9e0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
1c9f0 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
1ca00 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
1ca10 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
1ca20 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
1ca30 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
1ca40 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
1ca50 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
1ca60 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1ca70 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
1ca80 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
1ca90 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
1caa0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
1cab0 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
1cac0 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
1cad0 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
1cae0 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
1caf0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
1cb00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
1cb10 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
1cb20 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
1cb30 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
1cb40 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
1cb50 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
1cb60 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
1cb70 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
1cb80 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
1cb90 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
1cba0 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
1cbb0 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
1cbc0 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
1cbd0 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
1cbe0 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
1cbf0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
1cc00 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
1cc10 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
1cc20 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
1cc30 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
1cc40 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
1cc50 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
1cc60 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
1cc70 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
1cc80 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
1cc90 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
1cca0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1ccb0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
1ccc0 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
1ccd0 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
1cce0 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
1ccf0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
1cd00 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
1cd10 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
1cd20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
1cd30 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1cd40 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
1cd50 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
1cd60 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
1cd70 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
1cd80 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
1cd90 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
1cda0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
1cdb0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
1cdc0 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
1cdd0 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
1cde0 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
1cdf0 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
1ce00 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
1ce10 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
1ce20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
1ce30 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  es..*/.int sqlit
1ce40 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
1ce50 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
1ce60 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
1ce70 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1ce80 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
1ce90 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
1cea0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
1ceb0 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
1cec0 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
1ced0 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
1cee0 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
1cef0 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
1cf00 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
1cf10 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
1cf20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
1cf30 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
1cf40 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
1cf50 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
1cf60 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
1cf70 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
1cf80 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
1cf90 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
1cfa0 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
1cfb0 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
1cfc0 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
1cfd0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1cfe0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
1cff0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1d000 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
1d010 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
1d020 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
1d030 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
1d040 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1d050 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
1d060 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
1d070 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
1d080 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
1d090 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
1d0a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1d0b0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d0c0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
1d0d0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d0e0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1d0f0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
1d100 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
1d110 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
1d120 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
1d130 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1d140 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1d150 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
1d160 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
1d170 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
1d180 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
1d190 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1d1a0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
1d1b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1d1c0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1d1d0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
1d1e0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
1d1f0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1d200 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1d210 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
1d220 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
1d230 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d240 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
1d250 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
1d260 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
1d270 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1d280 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
1d290 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  P</dt>.** <dd>Th
1d2a0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1d2b0 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73   of instructions
1d2c0 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61   in a virtual ma
1d2d0 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a  chine program.**
1d2e0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1d2f0 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  nt an SQL statem
1d300 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74  ent.  This limit
1d310 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
1d320 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74  y.** enforced, t
1d330 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74  hough that might
1d340 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d   be added in som
1d350 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  e future release
1d360 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f   of.** SQLite.</
1d370 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1d380 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
1d390 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
1d3a0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1d3b0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
1d3c0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
1d3d0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
1d3e0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1d3f0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
1d400 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1d410 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1d420 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
1d430 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
1d440 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28  )^</dd>.**.** ^(
1d450 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1d460 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1d470 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1d480 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
1d490 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65  gth of the patte
1d4a0 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rn argument to t
1d4b0 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20  he [LIKE] or.** 
1d4c0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73  [GLOB] operators
1d4d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1d4e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1d4f0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1d500 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
1d510 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
1d520 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
1d530 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
1d540 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
1d550 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1d560 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
1d570 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
1d580 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1d590 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
1d5a0 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
1d5b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
1d5c0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1d5d0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
1d5e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1d5f0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
1d600 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1d610 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
1d620 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
1d630 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
1d640 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
1d650 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
1d660 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1d670 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
1d680 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
1d690 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
1d6a0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
1d6b0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
1d6c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
1d6d0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
1d6e0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
1d6f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
1d700 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
1d710 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
1d720 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1d730 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
1d740 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
1d750 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1d760 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
1d770 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
1d780 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1d790 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1d7a0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
1d7b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1d7c0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
1d7d0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
1d7e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d7f0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
1d800 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
1d810 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
1d820 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
1d830 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
1d840 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
1d850 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
1d860 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
1d870 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
1d880 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
1d890 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1d8a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
1d8b0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
1d8c0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
1d8d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
1d8e0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
1d8f0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
1d900 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
1d910 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
1d920 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
1d930 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
1d940 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
1d950 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d960 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
1d970 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
1d980 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
1d990 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
1d9a0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
1d9b0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
1d9c0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
1d9d0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
1d9e0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
1d9f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
1da00 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
1da10 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
1da20 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
1da30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1da40 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
1da50 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
1da60 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
1da70 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
1da80 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
1da90 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
1daa0 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
1dab0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
1dac0 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
1dad0 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
1dae0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1daf0 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
1db00 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
1db10 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
1db20 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
1db30 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
1db40 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
1db50 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
1db60 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
1db70 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
1db80 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
1db90 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
1dba0 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
1dbb0 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
1dbc0 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
1dbd0 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
1dbe0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
1dbf0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
1dc00 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
1dc10 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
1dc20 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
1dc30 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
1dc40 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
1dc50 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
1dc60 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
1dc70 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
1dc80 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
1dc90 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
1dca0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
1dcb0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
1dcc0 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a  nator bytes..**.
1dcd0 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
1dce0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
1dcf0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
1dd00 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
1dd10 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
1dd20 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
1dd30 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
1dd40 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
1dd50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
1dd60 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
1dd70 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
1dd80 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
1dd90 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
1dda0 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
1ddb0 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
1ddc0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
1ddd0 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
1dde0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
1ddf0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
1de00 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
1de10 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
1de20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1de30 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
1de40 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
1de50 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
1de60 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
1de70 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
1de80 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
1de90 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
1dea0 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
1deb0 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
1dec0 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
1ded0 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
1dee0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
1def0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
1df00 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
1df10 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
1df20 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1df30 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
1df40 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
1df50 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
1df60 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
1df70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
1df80 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
1df90 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
1dfa0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
1dfb0 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
1dfc0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
1dfd0 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
1dfe0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1dff0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1e000 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
1e010 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1e020 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1e030 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
1e040 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
1e050 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
1e060 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
1e070 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
1e080 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
1e090 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
1e0a0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1e0b0 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
1e0c0 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
1e0d0 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
1e0e0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
1e0f0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
1e100 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
1e110 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
1e120 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
1e130 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
1e140 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
1e150 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
1e160 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
1e170 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
1e180 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
1e190 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
1e1a0 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
1e1b0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
1e1c0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
1e1d0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
1e1e0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
1e1f0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
1e200 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
1e210 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
1e220 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
1e230 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1e240 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
1e250 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
1e260 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
1e270 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
1e280 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c  it again..** </l
1e290 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
1e2a0 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
1e2b0 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
1e2c0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
1e2d0 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
1e2e0 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
1e2f0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
1e300 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
1e310 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
1e320 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
1e330 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
1e340 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
1e350 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
1e360 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
1e370 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
1e380 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
1e390 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
1e3a0 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
1e3b0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
1e3c0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
1e3d0 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
1e3e0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
1e3f0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
1e400 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
1e410 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
1e420 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
1e430 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
1e440 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
1e450 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1e460 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
1e470 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
1e480 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
1e490 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
1e4a0 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
1e4b0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
1e4c0 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
1e4d0 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
1e4e0 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
1e4f0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
1e500 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
1e510 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
1e520 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
1e530 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
1e540 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
1e550 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
1e560 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
1e570 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
1e580 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
1e590 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
1e5a0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
1e5b0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
1e5c0 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
1e5d0 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
1e5e0 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
1e5f0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
1e600 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
1e610 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
1e620 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
1e630 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
1e640 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
1e650 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
1e660 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
1e670 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
1e680 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
1e690 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
1e6a0 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
1e6b0 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
1e6c0 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
1e6d0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
1e6e0 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT2] compile-ti
1e6f0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
1e700 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a  bled..** the .**
1e710 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
1e720 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  */.int sqlite3_p
1e730 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
1e740 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1e750 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
1e760 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1e770 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1e780 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
1e790 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
1e7a0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
1e7b0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
1e7c0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
1e7d0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
1e7e0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
1e7f0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
1e800 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
1e810 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
1e820 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
1e830 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
1e840 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
1e850 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
1e860 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
1e870 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20  3_prepare_v2(.  
1e880 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1e890 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1e8a0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1e8b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1e8c0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1e8d0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
1e8e0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
1e8f0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
1e900 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
1e910 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
1e920 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
1e930 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
1e940 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
1e950 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
1e960 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1e970 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
1e980 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
1e990 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
1e9a0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
1e9b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1e9c0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
1e9d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
1e9e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
1e9f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1ea00 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
1ea10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
1ea20 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
1ea30 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
1ea40 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
1ea50 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
1ea60 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
1ea70 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
1ea80 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
1ea90 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
1eaa0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
1eab0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
1eac0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
1ead0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
1eae0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
1eaf0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
1eb00 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71  epare16_v2(.  sq
1eb10 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1eb20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1eb30 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1eb40 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1eb50 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1eb60 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1eb70 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1eb80 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1eb90 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1eba0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1ebb0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1ebc0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1ebd0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1ebe0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1ebf0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1ec00 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1ec10 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1ec20 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1ec30 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  zSql */.);../*.*
1ec40 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72  * CAPI3REF: Retr
1ec50 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74  ieving Statement
1ec60 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73   SQL.**.** ^This
1ec70 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1ec80 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65  e used to retrie
1ec90 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20  ve a saved copy 
1eca0 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a  of the original.
1ecb0 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64  ** SQL text used
1ecc0 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72   to create a [pr
1ecd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1ece0 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d  ] if that statem
1ecf0 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69  ent was.** compi
1ed00 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  led using either
1ed10 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ed20 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
1ed30 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1ed40 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
1ed50 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
1ed60 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
1ed70 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
1ed80 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
1ed90 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
1eda0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
1edb0 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
1edc0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
1edd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
1ede0 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
1edf0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
1ee00 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
1ee10 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
1ee20 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
1ee30 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
1ee40 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
1ee50 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
1ee60 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
1ee70 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
1ee80 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
1ee90 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
1eea0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
1eeb0 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
1eec0 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
1eed0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
1eee0 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
1eef0 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
1ef00 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
1ef10 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
1ef20 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
1ef30 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
1ef40 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
1ef50 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
1ef60 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
1ef70 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
1ef80 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
1ef90 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
1efa0 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
1efb0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
1efc0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
1efd0 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
1efe0 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
1eff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
1f000 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
1f010 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
1f020 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
1f030 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
1f040 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
1f050 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
1f060 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
1f070 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
1f080 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
1f090 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
1f0a0 68 65 6c 64 2e 20 20 41 20 69 6e 74 65 72 6e 61  held.  A interna
1f0b0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
1f0c0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
1f0d0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1f0e0 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
1f0f0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
1f100 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
1f110 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
1f120 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
1f130 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
1f140 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
1f150 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
1f160 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1f170 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
1f180 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1f190 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
1f1a0 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
1f1b0 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
1f1c0 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
1f1d0 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
1f1e0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
1f1f0 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
1f200 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
1f210 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
1f220 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
1f230 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
1f240 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
1f250 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
1f260 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
1f270 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
1f280 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
1f290 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
1f2a0 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
1f2b0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
1f2c0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
1f2d0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
1f2e0 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
1f2f0 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
1f300 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
1f310 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
1f320 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
1f330 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
1f340 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
1f350 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
1f360 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f370 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
1f380 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
1f390 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
1f3a0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
1f3b0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
1f3c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
1f3d0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
1f3e0 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
1f3f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f400 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
1f410 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
1f420 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
1f430 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
1f440 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
1f450 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
1f460 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
1f470 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
1f480 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
1f490 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
1f4a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
1f4b0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
1f4c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
1f4d0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
1f4e0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
1f4f0 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
1f500 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
1f510 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1f520 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
1f530 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
1f540 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
1f550 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1f560 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
1f570 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
1f580 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
1f590 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
1f5a0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
1f5b0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
1f5c0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
1f5d0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
1f5e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
1f5f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
1f600 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
1f610 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
1f620 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
1f630 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
1f640 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
1f650 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
1f660 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
1f670 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
1f680 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
1f690 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
1f6a0 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
1f6b0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
1f6c0 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
1f6d0 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
1f6e0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
1f6f0 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
1f700 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
1f710 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1f720 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
1f730 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
1f740 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
1f750 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
1f760 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
1f770 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
1f780 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
1f790 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
1f7a0 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
1f7b0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
1f7c0 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
1f7d0 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
1f7e0 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
1f7f0 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
1f800 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
1f810 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
1f820 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
1f830 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
1f840 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
1f850 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
1f860 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ng}.**.** ^(In t
1f870 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1f880 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
1f890 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f8a0 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
1f8b0 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
1f8c0 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
1f8d0 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
1f8e0 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
1f8f0 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
1f900 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
1f910 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
1f920 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
1f930 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
1f940 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
1f950 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
1f960 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
1f970 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
1f980 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
1f990 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
1f9a0 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
1f9b0 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
1f9c0 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
1f9d0 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
1f9e0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
1f9f0 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
1fa00 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
1fa10 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
1fa20 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
1fa30 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
1fa40 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
1fa50 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
1fa60 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
1fa70 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
1fa80 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1fa90 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
1faa0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
1fab0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
1fac0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
1fad0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
1fae0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
1faf0 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
1fb00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1fb10 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1fb20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
1fb30 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
1fb40 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
1fb50 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
1fb60 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
1fb70 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
1fb80 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
1fb90 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
1fba0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
1fbb0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
1fbc0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
1fbd0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
1fbe0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
1fbf0 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
1fc00 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
1fc10 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
1fc20 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
1fc30 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
1fc40 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
1fc50 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
1fc60 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
1fc70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
1fc80 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
1fc90 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
1fca0 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
1fcb0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
1fcc0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
1fcd0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
1fce0 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
1fcf0 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
1fd00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
1fd10 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
1fd20 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
1fd30 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
1fd40 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
1fd50 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
1fd60 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
1fd70 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
1fd80 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
1fd90 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1fda0 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
1fdb0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
1fdc0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
1fdd0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
1fde0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
1fdf0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
1fe00 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
1fe10 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
1fe20 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1fe30 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
1fe40 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
1fe50 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
1fe60 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
1fe70 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
1fe80 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67  parameter is neg
1fe90 61 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74  ative, the lengt
1fea0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
1feb0 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
1fec0 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
1fed0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
1fee0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a  erminator..**.**
1fef0 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
1ff00 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
1ff10 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  bind_blob(), sql
1ff20 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
1ff30 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  , and.** sqlite3
1ff40 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69  _bind_text16() i
1ff50 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
1ff60 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
1ff70 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
1ff80 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
1ff90 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
1ffa0 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
1ffb0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
1ffc0 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
1ffd0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
1ffe0 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
1fff0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71  f the call to sq
20000 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
20010 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  ),.** sqlite3_bi
20020 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71  nd_text(), or sq
20030 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
20040 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20  6() fails.  .** 
20050 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
20060 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
20070 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
20080 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
20090 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
200a0 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
200b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
200c0 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
200d0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
200e0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
200f0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
20100 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
20110 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
20120 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
20130 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
20140 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
20150 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
20160 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
20170 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
20180 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
20190 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
201a0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
201b0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
201c0 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
201d0 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
201e0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
201f0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
20200 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
20210 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
20220 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
20230 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
20240 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
20250 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
20260 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
20270 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
20280 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
20290 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
202a0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
202b0 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
202c0 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
202d0 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
202e0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
202f0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
20300 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
20310 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
20320 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
20330 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
20340 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
20350 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
20360 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
20370 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
20380 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
20390 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
203a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
203b0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
203c0 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
203d0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
203e0 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
203f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
20400 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
20410 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
20420 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
20430 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
20440 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
20450 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
20460 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
20470 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
20480 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
20490 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
204a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
204b0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
204c0 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
204d0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
204e0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
204f0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
20500 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
20510 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
20520 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
20530 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
20540 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
20550 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
20560 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
20570 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
20580 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
20590 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
205a0 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
205b0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
205c0 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
205d0 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
205e0 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
205f0 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
20600 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
20610 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
20620 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
20630 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
20640 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
20650 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
20660 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
20670 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
20680 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
20690 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
206a0 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
206b0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
206c0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
206d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
206e0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
206f0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
20700 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
20710 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
20720 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
20730 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
20740 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
20750 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
20760 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
20770 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
20780 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
20790 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
207a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
207b0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
207c0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
207d0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
207e0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
207f0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
20800 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
20810 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
20820 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
20830 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
20840 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
20850 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
20860 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
20870 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
20880 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
20890 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71  e3_bind_value(sq
208a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
208b0 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f  , const sqlite3_
208c0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
208d0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
208e0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
208f0 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
20900 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20910 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
20920 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e  rameters.**.** ^
20930 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
20940 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
20950 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
20960 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
20970 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
20980 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
20990 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
209a0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
209b0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
209c0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
209d0 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
209e0 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
209f0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
20a00 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
20a10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
20a20 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
20a30 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
20a40 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
20a50 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
20a60 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
20a70 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
20a80 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
20a90 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
20aa0 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
20ab0 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
20ac0 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
20ad0 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
20ae0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
20af0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
20b00 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
20b10 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
20b20 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
20b30 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
20b40 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
20b50 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
20b60 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
20b70 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
20b80 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
20b90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20ba0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
20bb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
20bc0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
20bd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
20be0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
20bf0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
20c00 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
20c10 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
20c20 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
20c30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
20c40 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
20c50 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
20c60 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
20c70 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
20c80 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
20c90 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
20ca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
20cb0 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
20cc0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
20cd0 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
20ce0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
20cf0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
20d00 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
20d10 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
20d20 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
20d30 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
20d40 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
20d50 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
20d60 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
20d70 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
20d80 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
20d90 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
20da0 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
20db0 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
20dc0 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
20dd0 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
20de0 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
20df0 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
20e00 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
20e10 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
20e20 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
20e30 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
20e40 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
20e50 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
20e60 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
20e70 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
20e80 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
20e90 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
20ea0 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
20eb0 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
20ec0 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
20ed0 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
20ee0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
20ef0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
20f00 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
20f10 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
20f20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
20f30 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
20f40 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
20f50 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
20f60 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
20f70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
20f80 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
20f90 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
20fa0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
20fb0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
20fc0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
20fd0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
20fe0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
20ff0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21000 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f  _index()]..*/.co
21010 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
21020 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21030 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
21040 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
21050 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
21060 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
21070 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
21080 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  me.**.** ^Return
21090 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
210a0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
210b0 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
210c0 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
210d0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
210e0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
210f0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
21100 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
21110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
21120 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
21130 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
21140 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
21150 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
21160 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
21170 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
21180 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
21190 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
211a0 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
211b0 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
211c0 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
211d0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
211e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
211f0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
21200 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
21210 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
21220 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
21230 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
21240 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
21250 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
21260 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21270 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
21280 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
21290 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
212a0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
212b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
212c0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
212d0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
212e0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
212f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
21300 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
21310 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
21320 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
21330 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
21340 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
21350 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
21360 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
21370 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
21380 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
21390 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
213a0 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
213b0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
213c0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20  to NULL..*/.int 
213d0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
213e0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
213f0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
21400 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
21410 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
21420 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
21430 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
21440 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
21450 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
21460 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
21470 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
21480 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
21490 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
214a0 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
214b0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
214c0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
214d0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
214e0 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
214f0 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
21500 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
21510 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
21520 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
21530 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  mn_count(sqlite3
21540 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
21550 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21560 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20  Column Names In 
21570 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
21580 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
21590 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
215a0 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
215b0 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
215c0 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
215d0 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
215e0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
215f0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
21600 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
21610 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
21620 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
21630 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
21640 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
21650 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
21660 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
21670 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
21680 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
21690 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
216a0 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
216b0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
216c0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
216d0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
216e0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
216f0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
21700 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
21710 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
21720 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
21730 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
21740 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
21750 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
21760 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
21770 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
21780 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
21790 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
217a0 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
217b0 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
217c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
217d0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
217e0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
217f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
21800 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
21810 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
21820 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
21830 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
21840 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
21850 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
21860 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
21870 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
21880 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
21890 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
218a0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
218b0 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
218c0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
218d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
218e0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
218f0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
21900 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
21910 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
21920 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
21930 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
21940 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
21950 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
21960 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
21970 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
21980 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
21990 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
219a0 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
219b0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
219c0 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
219d0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
219e0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
219f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
21a00 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
21a10 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
21a20 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
21a30 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
21a40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
21a50 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
21a60 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
21a70 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
21a80 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
21a90 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
21aa0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
21ab0 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
21ac0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
21ad0 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
21ae0 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
21af0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
21b00 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
21b10 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
21b20 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
21b30 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
21b40 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
21b50 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
21b60 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
21b70 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
21b80 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
21b90 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
21ba0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
21bb0 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
21bc0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
21bd0 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
21be0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
21bf0 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
21c00 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
21c10 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
21c20 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
21c30 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
21c40 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21c50 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
21c60 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
21c70 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
21c80 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d  or until the sam
21c90 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  e information is
21ca0 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67   requested.** ag
21cb0 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65  ain in a differe
21cc0 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a  nt encoding..**.
21cd0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65  ** ^The names re
21ce0 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f  turned are the o
21cf0 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73  riginal un-alias
21d00 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a  ed names of the.
21d10 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ** database, tab
21d20 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a  le, and column..
21d30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
21d40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
21d50 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73  se interfaces is
21d60 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
21d70 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65  tement]..** ^The
21d80 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
21d90 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
21da0 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65  about the Nth re
21db0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75  sult column retu
21dc0 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73  rned by.** the s
21dd0 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20  tatement, where 
21de0 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
21df0 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
21e00 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d  t..** ^The left-
21e10 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63  most column is c
21e20 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73  olumn 0 for thes
21e30 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
21e40 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f  * ^If the Nth co
21e50 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
21e60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
21e70 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20  s an expression 
21e80 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61  or.** subquery a
21e90 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75  nd is not a colu
21ea0 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61  mn value, then a
21eb0 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  ll of these func
21ec0 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20  tions return.** 
21ed0 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f  NULL.  ^These ro
21ee0 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f  utine might also
21ef0 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20   return NULL if 
21f00 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
21f10 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63  ion error.** occ
21f20 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65  urs.  ^Otherwise
21f30 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68  , they return th
21f40 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74  e name of the at
21f50 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c  tached database,
21f60 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f   table,.** or co
21f70 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20  lumn that query 
21f80 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61  result column wa
21f90 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d  s extracted from
21fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68  ..**.** ^As with
21fb0 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74   all other SQLit
21fc0 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68  e APIs, those wh
21fd0 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69  ose names end wi
21fe0 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a  th "16" return.*
21ff0 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  * UTF-16 encoded
22000 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65   strings and the
22010 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73   other functions
22020 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a   return UTF-8..*
22030 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73  *.** ^These APIs
22040 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61   are only availa
22050 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61  ble if the libra
22060 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  ry was compiled 
22070 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
22080 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d  ITE_ENABLE_COLUM
22090 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72  N_METADATA] C-pr
220a0 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f  eprocessor symbo
220b0 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  l..**.** If two 
220c0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
220d0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
220e0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
220f0 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73  es against the s
22100 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  ame.** prepared 
22110 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f  statement and co
22120 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65  lumn at the same
22130 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
22140 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e  esults are.** un
22150 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  defined..**.** I
22160 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
22170 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
22180 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  r more.** [sqlit
22190 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
221a0 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e  se_name | column
221b0 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66   metadata interf
221c0 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65  aces].** for the
221d0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
221e0 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72  statement] and r
221f0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  esult column.** 
22200 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
22210 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
22220 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
22230 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
22240 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
22250 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
22260 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
22270 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
22280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
22290 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
222a0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
222b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
222c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
222d0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
222e0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
222f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
22300 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
22310 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
22320 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
22330 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
22340 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
22350 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
22360 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
22370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
22380 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  in_name16(sqlite
22390 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
223a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
223b0 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70 65  eclared Datatype
223c0 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73 75   Of A Query Resu
223d0 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  lt.**.** ^(The f
223e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
223f0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
22400 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
22410 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
22420 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
22430 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
22440 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
22450 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
22460 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
22470 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
22480 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
22490 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
224a0 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
224b0 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
224c0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
224d0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
224e0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
224f0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
22500 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
22510 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
22520 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
22530 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
22540 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
22550 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
22560 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
22570 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
22580 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
22590 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
225a0 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
225b0 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
225c0 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
225d0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
225e0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
225f0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
22600 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
22610 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
22620 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
22630 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
22640 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
22650 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
22660 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
22670 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
22680 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
22690 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
226a0 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
226b0 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
226c0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
226d0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
226e0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
226f0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
22700 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
22710 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
22720 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
22730 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
22740 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
22750 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
22760 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
22770 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
22780 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
22790 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
227a0 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
227b0 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
227c0 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
227d0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
227e0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
227f0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
22800 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
22810 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
22820 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f  se values..*/.co
22830 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
22840 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70  3_column_decltyp
22850 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
22860 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
22870 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
22880 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69  _decltype16(sqli
22890 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
228a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
228b0 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c   Evaluate An SQL
228c0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   Statement.**.**
228d0 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72   After a [prepar
228e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61  ed statement] ha
228f0 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20  s been prepared 
22900 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20  using either.** 
22910 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22920 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
22930 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
22940 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  )] or one of the
22950 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
22960 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70  faces [sqlite3_p
22970 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71  repare()] or [sq
22980 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
22990 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  )], this functio
229a0 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c  n.** must be cal
229b0 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  led one or more 
229c0 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74  times to evaluat
229d0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e  e the statement.
229e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69  .**.** The detai
229f0 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69  ls of the behavi
22a00 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  or of the sqlite
22a10 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61  3_step() interfa
22a20 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20  ce depend.** on 
22a30 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74  whether the stat
22a40 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72  ement was prepar
22a50 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77  ed using the new
22a60 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  er "v2" interfac
22a70 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  e.** [sqlite3_pr
22a80 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
22a90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22aa0 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20  16_v2()] or the 
22ab0 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20  older legacy.** 
22ac0 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74  interface [sqlit
22ad0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
22ae0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
22af0 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73  re16()].  The us
22b00 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20  e of the.** new 
22b10 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
22b20 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
22b30 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  r new applicatio
22b40 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63  ns but the legac
22b50 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77  y.** interface w
22b60 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ill continue to 
22b70 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a  be supported..**
22b80 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61  .** ^In the lega
22b90 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
22ba0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77  e return value w
22bb0 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53  ill be either [S
22bc0 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20  QLITE_BUSY],.** 
22bd0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b  [SQLITE_DONE], [
22be0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51  SQLITE_ROW], [SQ
22bf0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20  LITE_ERROR], or 
22c00 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
22c10 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76  .** ^With the "v
22c20 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e  2" interface, an
22c30 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b  y of the other [
22c40 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72  result codes] or
22c50 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
22c60 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68  sult codes] migh
22c70 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  t be returned as
22c80 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   well..**.** ^[S
22c90 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e  QLITE_BUSY] mean
22ca0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
22cb0 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75  ase engine was u
22cc0 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65  nable to acquire
22cd0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
22ce0 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20   locks it needs 
22cf0 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20  to do its job.  
22d00 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ^If the statemen
22d10 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a  t is a [COMMIT].
22d20 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74  ** or occurs out
22d30 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69  side of an expli
22d40 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
22d50 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65   then you can re
22d60 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  try the.** state
22d70 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74  ment.  If the st
22d80 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61  atement is not a
22d90 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63   [COMMIT] and oc
22da0 63 75 72 73 20 77 69 74 68 69 6e 20 61 0a 2a 2a  curs within a.**
22db0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
22dc0 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
22dd0 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
22de0 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
22df0 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
22e00 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
22e10 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
22e20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
22e30 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
22e40 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
22e50 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
22e60 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
22e70 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
22e80 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
22e90 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
22ea0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
22eb0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
22ec0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
22ed0 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
22ee0 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
22ef0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
22f00 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
22f10 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
22f20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
22f30 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
22f40 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
22f50 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
22f60 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
22f70 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
22f80 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
22f90 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
22fa0 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
22fb0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
22fc0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
22fd0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
22fe0 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
22ff0 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
23000 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
23010 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
23020 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
23030 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
23040 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
23050 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
23060 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
23070 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
23080 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
23090 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
230a0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
230b0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
230c0 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
230d0 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
230e0 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
230f0 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
23100 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
23110 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
23120 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
23130 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
23140 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
23150 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
23160 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
23170 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
23180 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
23190 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
231a0 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
231b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
231c0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
231d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
231e0 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
231f0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
23200 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
23210 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
23220 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
23230 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
23240 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
23250 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
23260 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
23270 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
23280 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
23290 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
232a0 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
232b0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
232c0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
232d0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
232e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
232f0 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
23300 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
23310 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
23320 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
23330 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
23340 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
23350 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
23360 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
23370 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
23380 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
23390 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
233a0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
233b0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
233c0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
233d0 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
233e0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
233f0 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
23400 67 20 33 2e 36 2e 32 33 2e 31 2c 20 69 74 20 77  g 3.6.23.1, it w
23410 61 73 20 72 65 71 75 69 72 65 64 0a 2a 2a 20 61  as required.** a
23420 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
23430 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
23440 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
23450 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 74 68   [SQLITE_ROW] th
23460 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  at.** [sqlite3_r
23470 65 73 65 74 28 29 5d 20 62 65 20 63 61 6c 6c 65  eset()] be calle
23480 64 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  d before any sub
23490 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
234a0 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
234b0 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
234c0 65 20 74 6f 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  e to invoke [sql
234d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 69 6e  ite3_reset()] in
234e0 20 74 68 69 73 20 77 61 79 20 77 6f 75 6c 64 0a   this way would.
234f0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ** result in an 
23500 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
23510 72 65 74 75 72 6e 20 66 72 6f 6d 20 73 71 6c 69  return from sqli
23520 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
23530 20 61 66 74 65 72 0a 2a 2a 20 76 65 72 73 69 6f   after.** versio
23540 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
23550 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
23560 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
23570 33 5f 72 65 73 65 74 28 29 5d 20 0a 2a 2a 20 61  3_reset()] .** a
23580 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
23590 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
235a0 65 20 72 61 74 68 65 72 20 74 68 61 6e 20 72 65  e rather than re
235b0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
235c0 4d 49 53 55 53 45 5d 2e 20 20 0a 2a 2a 0a 2a 2a  MISUSE].  .**.**
235d0 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
235e0 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
235f0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
23600 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
23610 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
23620 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
23630 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
23640 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
23650 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
23660 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
23670 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
23680 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
23690 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
236a0 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
236b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
236c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
236d0 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
236e0 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
236f0 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
23700 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
23710 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
23720 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
23730 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
23740 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
23750 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
23760 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
23770 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
23780 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
23790 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
237a0 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
237b0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
237c0 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
237d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
237e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
237f0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
23800 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
23810 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
23820 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
23830 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
23840 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
23850 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
23860 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
23870 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
23880 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
23890 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
238a0 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
238b0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
238c0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
238d0 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
238e0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
238f0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
23900 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
23910 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
23920 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a  result set.**.**
23930 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
23940 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
23950 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
23960 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
23970 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
23980 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
23990 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
239a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
239b0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
239c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
239d0 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
239e0 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
239f0 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
23a00 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
23a10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
23a20 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
23a30 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
23a40 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
23a50 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
23a60 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
23a70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23a80 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
23a90 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
23aa0 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
23ab0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
23ac0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
23ad0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
23ae0 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nt()].*/.int sql
23af0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
23b00 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
23b10 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
23b20 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74  I3REF: Fundament
23b30 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20  al Datatypes.** 
23b40 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
23b50 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  _TEXT.**.** ^(Ev
23b60 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c  ery value in SQL
23b70 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66  ite has one of f
23b80 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20  ive fundamental 
23b90 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a  datatypes:.**.**
23ba0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34   <ul>.** <li> 64
23bb0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
23bc0 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ger.** <li> 64-b
23bd0 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67  it IEEE floating
23be0 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a   point number.**
23bf0 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20   <li> string.** 
23c00 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69  <li> BLOB.** <li
23c10 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29  > NULL.** </ul>)
23c20 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  ^.**.** These co
23c30 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65  nstants are code
23c40 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68  s for each of th
23c50 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a  ose types..**.**
23c60 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53   Note that the S
23c70 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74  QLITE_TEXT const
23c80 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65  ant was also use
23c90 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73  d in SQLite vers
23ca0 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63  ion 2.** for a c
23cb0 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72  ompletely differ
23cc0 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f  ent meaning.  So
23cd0 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b  ftware that link
23ce0 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a  s against both.*
23cf0 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
23d00 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65   2 and SQLite ve
23d10 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75  rsion 3 should u
23d20 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c  se SQLITE3_TEXT,
23d30 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54   not.** SQLITE_T
23d40 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  EXT..*/.#define 
23d50 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20  SQLITE_INTEGER  
23d60 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
23d70 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66  _FLOAT    2.#def
23d80 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20  ine SQLITE_BLOB 
23d90 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
23da0 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a  LITE_NULL     5.
23db0 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45  #ifdef SQLITE_TE
23dc0 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  XT.# undef SQLIT
23dd0 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64  E_TEXT.#else.# d
23de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58  efine SQLITE_TEX
23df0 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23  T     3.#endif.#
23e00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54  define SQLITE3_T
23e10 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a  EXT     3../*.**
23e20 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
23e30 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20  t Values From A 
23e40 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44  Query.** KEYWORD
23e50 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  S: {column acces
23e60 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a  s functions}.**.
23e70 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
23e80 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75  s form the "resu
23e90 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63  lt set" interfac
23ea0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e..**.** ^These 
23eb0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
23ec0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
23ed0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
23ee0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
23ef0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
23f00 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
23f10 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
23f20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
23f30 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
23f40 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
23f50 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
23f60 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
23f70 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
23f80 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
23f90 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
23fa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
23fb0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
23fc0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
23fd0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
23fe0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
23ff0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
24000 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
24010 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
24020 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
24030 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
24040 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
24050 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
24060 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
24070 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
24080 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
24090 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
240a0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
240b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
240c0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
240d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
240e0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
240f0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
24100 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
24110 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
24120 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
24130 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
24140 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
24150 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
24160 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
24170 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
24180 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
24190 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
241a0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
241b0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
241c0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
241d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
241e0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
241f0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
24200 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
24210 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
24220 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
24230 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
24240 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
24250 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
24260 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24270 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
24280 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
24290 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
242a0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
242b0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
242c0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
242d0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
242e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
242f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
24300 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
24310 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
24320 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
24330 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
24340 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
24350 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
24360 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
24370 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
24380 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
24390 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
243a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
243b0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
243c0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
243d0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
243e0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
243f0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
24400 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
24410 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
24420 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
24430 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
24440 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
24450 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
24460 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
24470 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
24480 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
24490 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
244a0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
244b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
244c0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
244d0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
244e0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
244f0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
24500 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
24510 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
24520 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
24530 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
24540 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
24550 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
24560 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
24570 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
24580 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
24590 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
245a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
245b0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
245c0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
245d0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
245e0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
245f0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
24600 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
24610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
24620 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
24630 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
24640 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
24650 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
24660 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
24670 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
24680 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
24690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
246a0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
246b0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
246c0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
246d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
246e0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
246f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
24700 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
24710 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
24720 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
24730 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
24740 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
24750 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
24760 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
24770 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
24780 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
24790 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
247a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
247b0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
247c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
247d0 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
247e0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
247f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
24800 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
24810 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
24820 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
24830 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
24840 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
24850 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
24860 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
24870 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
24880 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
24890 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
248a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
248b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
248c0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
248d0 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
248e0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
248f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
24900 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
24910 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
24920 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
24930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
24940 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
24950 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
24960 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
24970 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
24980 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
24990 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
249a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
249b0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
249c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
249d0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
249e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
249f0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
24a00 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
24a10 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
24a20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
24a30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
24a40 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
24a50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
24a60 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
24a70 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
24a80 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
24a90 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
24aa0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
24ab0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
24ac0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
24ad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
24ae0 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
24af0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
24b00 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
24b10 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
24b20 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
24b30 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
24b40 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
24b50 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
24b60 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
24b70 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
24b80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
24b90 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
24ba0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
24bb0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
24bc0 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54   terminated.  ^T
24bd0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
24be0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
24bf0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
24c00 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
24c10 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
24c20 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
24c30 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
24c40 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
24c50 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
24c60 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
24c70 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
24c80 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20  ue] object.  An 
24c90 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
24ca0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
24cb0 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
24cc0 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74  used with [sqlit
24cd0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
24ce0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
24cf0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
24d00 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
24d10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
24d20 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
24d30 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
24d40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
24d50 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
24d60 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
24d70 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
24d80 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
24d90 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
24da0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
24db0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
24dc0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
24dd0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
24de0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
24df0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
24e00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
24e10 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
24e20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
24e30 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
24e40 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
24e50 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
24e60 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
24e70 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
24e80 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
24e90 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
24ea0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
24eb0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
24ec0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
24ed0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
24ee0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
24ef0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
24f00 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
24f10 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
24f20 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
24f30 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
24f40 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
24f50 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
24f60 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
24f70 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
24f80 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
24f90 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
24fa0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
24fb0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
24fc0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
24fd0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
24fe0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
24ff0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
25000 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
25010 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
25020 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
25030 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
25040 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
25050 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
25060 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
25070 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
25080 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70  Result is NULL p
25090 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
250a0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
250b0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
250c0 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74  Convert from int
250d0 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a  eger to float.**
250e0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
250f0 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20  R  <td>   TEXT  
25100 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
25110 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e  dering of the in
25120 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
25130 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
25140 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53    BLOB    <td> S
25150 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e  ame as INTEGER->
25160 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  TEXT.** <tr><td>
25170 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49    FLOAT   <td> I
25180 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f  NTEGER   <td> Co
25190 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74  nvert from float
251a0 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c   to integer.** <
251b0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
251c0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
251d0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
251e0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
251f0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
25200 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
25210 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
25220 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a  as FLOAT->TEXT.*
25230 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
25240 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
25250 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69     <td> Use atoi
25260 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
25270 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
25280 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20  OAT    <td> Use 
25290 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74  atof().** <tr><t
252a0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
252b0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
252c0 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72  No change.** <tr
252d0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
252e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
252f0 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
25300 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69  XT then use atoi
25310 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
25320 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
25330 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
25340 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e  ert to TEXT then
25350 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   use atof().** <
25360 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
25370 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
25380 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20  <td> Add a zero 
25390 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65  terminator if ne
253a0 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e  eded.** </table>
253b0 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  .** </blockquote
253c0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  >)^.**.** The ta
253d0 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20  ble above makes 
253e0 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61  reference to sta
253f0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20  ndard C library 
25400 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29  functions atoi()
25410 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20  .** and atof(). 
25420 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74   SQLite does not
25430 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73   really use thes
25440 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74  e functions.  It
25450 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20   has its.** own 
25460 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72  equivalent inter
25470 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54  nal routines.  T
25480 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74  he atoi() and at
25490 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a  of() names are.*
254a0 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61  * used in the ta
254b0 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20  ble for brevity 
254c0 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79  and because they
254d0 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f   are familiar to
254e0 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72   most.** C progr
254f0 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  ammers..**.** No
25500 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
25510 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
25520 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
25530 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
25540 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
25550 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
25560 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
25570 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
25580 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
25590 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
255a0 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
255b0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
255c0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
255d0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
255e0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
255f0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
25600 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
25610 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
25620 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
25630 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
25640 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
25650 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
25660 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
25670 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
25680 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
25690 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
256a0 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
256b0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
256c0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
256d0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
256e0 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
256f0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
25700 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
25710 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
25720 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
25730 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
25740 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
25750 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
25760 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
25770 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
25780 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
25790 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
257a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
257b0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
257c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
257d0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
257e0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
257f0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
25800 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
25810 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
25820 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
25830 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
25840 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
25850 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
25860 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
25870 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
25880 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
25890 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
258a0 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
258b0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
258c0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
258d0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
258e0 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
258f0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
25900 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
25910 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
25920 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
25930 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
25940 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
25950 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
25960 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
25970 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
25980 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
25990 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
259a0 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e  ** The safest an
259b0 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d  d easiest to rem
259c0 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20  ember policy is 
259d0 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
259e0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
259f0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
25a00 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
25a10 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
25a20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
25a30 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
25a40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
25a50 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
25a60 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
25a70 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
25a80 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
25a90 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
25aa0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
25ab0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
25ac0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
25ad0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
25ae0 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
25af0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
25b00 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
25b10 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
25b20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
25b30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
25b40 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
25b50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
25b60 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
25b70 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
25b80 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
25b90 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
25ba0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
25bb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
25bc0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
25bd0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
25be0 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
25bf0 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
25c00 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
25c10 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
25c20 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
25c30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
25c40 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
25c50 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
25c60 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
25c70 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
25c80 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
25c90 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
25ca0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
25cb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25cc0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
25cd0 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
25ce0 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
25cf0 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
25d00 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
25d10 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
25d20 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
25d30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25d40 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
25d50 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
25d60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
25d70 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
25d80 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
25d90 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
25da0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
25db0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
25dc0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e  ically.  Do <b>n
25dd0 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20  ot</b> pass the 
25de0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
25df0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
25e00 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
25e10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
25e20 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
25e30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
25e40 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
25e50 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
25e60 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
25e70 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
25e80 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
25e90 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
25ea0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
25eb0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
25ec0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
25ed0 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
25ee0 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
25ef0 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
25f00 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
25f10 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
25f20 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
25f30 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
25f40 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
25f50 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
25f60 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
25f70 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
25f80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
25f90 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
25fa0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
25fb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25fc0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
25fd0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
25fe0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
25ff0 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
26000 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
26010 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  ol);.double sqli
26020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c  te3_column_doubl
26030 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
26040 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
26050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
26060 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
26070 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
26080 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
26090 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
260a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
260b0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
260c0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
260d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
260e0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
260f0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
26100 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
26110 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
26120 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
26130 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
26140 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
26150 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
26160 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
26170 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
26180 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
26190 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
261a0 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
261b0 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
261c0 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
261d0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
261e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
261f0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
26200 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
26210 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
26220 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
26230 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
26240 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
26250 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
26260 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
26270 6e 6f 20 65 72 72 6f 72 73 20 6f 72 0a 2a 2a 20  no errors or.** 
26280 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
26290 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
262a0 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
262b0 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
262c0 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
262d0 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
262e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
262f0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
26300 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
26310 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
26320 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
26330 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
26340 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
26350 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
26360 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
26370 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
26380 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
26390 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
263a0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
263b0 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
263c0 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
263d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
263e0 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
263f0 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
26400 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
26410 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
26420 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
26430 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
26440 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
26450 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
26460 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
26470 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
26480 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
26490 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
264a0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
264b0 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
264c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
264d0 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
264e0 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
264f0 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
26500 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
26510 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
26520 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
26530 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
26540 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
26550 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
26560 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
26570 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
26580 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
26590 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
265a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
265b0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
265c0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
265d0 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
265e0 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
265f0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
26600 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
26610 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
26620 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
26630 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
26640 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
26650 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
26660 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
26670 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
26680 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
26690 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
266a0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
266b0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
266c0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
266d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  he sqlite3_reset
266e0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
266f0 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61  alled to reset a
26700 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
26710 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  ment].** object 
26720 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
26730 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79  ial state, ready
26740 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74   to be re-execut
26750 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20  ed..** ^Any SQL 
26760 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62  statement variab
26770 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c  les that had val
26780 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65  ues bound to the
26790 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b  m using.** the [
267a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
267b0 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  b | sqlite3_bind
267c0 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e  _*() API] retain
267d0 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a   their values..*
267e0 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63  * Use [sqlite3_c
267f0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d  lear_bindings()]
26800 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69   to reset the bi
26810 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ndings..**.** ^T
26820 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
26830 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
26840 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70  resets the [prep
26850 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26860 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65  S.** back to the
26870 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74   beginning of it
26880 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a  s program..**.**
26890 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
268a0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
268b0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
268c0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
268d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
268e0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
268f0 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54  E_ROW] or [SQLIT
26900 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69  E_DONE],.** or i
26910 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
26920 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65  S)] has never be
26930 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  fore been called
26940 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b   on S,.** then [
26950 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
26960 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  ] returns [SQLIT
26970 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  E_OK]..**.** ^If
26980 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
26990 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
269a0 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74  3_step(S)] for t
269b0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
269c0 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64  statement] S ind
269d0 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c  icated an error,
269e0 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65   then.** [sqlite
269f0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
26a00 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61  rns an appropria
26a10 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  te [error code].
26a20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
26a30 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
26a40 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f  nterface does no
26a50 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
26a60 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73  ues.** of any [s
26a70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
26a80 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68  |bindings] on th
26a90 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
26aa0 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74  ement] S..*/.int
26ab0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
26ac0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
26ad0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
26ae0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
26af0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
26b00 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
26b10 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
26b20 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
26b30 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
26b40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26b50 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
26b60 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
26b70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
26b80 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
26b90 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  }.**.** ^These f
26ba0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
26bb0 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
26bc0 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
26bd0 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
26be0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
26bf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
26c00 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
26c10 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
26c20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
26c30 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
26c40 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
26c50 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
26c60 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
26c70 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
26c80 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
26c90 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
26ca0 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 74  ted for.** the t
26cb0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
26cc0 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
26cd0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
26ce0 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
26cf0 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
26d00 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
26d10 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
26d20 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
26d30 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
26d40 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
26d50 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
26d60 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
26d70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26d80 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
26d90 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
26da0 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
26db0 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
26dc0 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
26dd0 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
26de0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
26df0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
26e00 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
26e10 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
26e20 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
26e30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26e40 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
26e50 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
26e60 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
26e70 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
26e80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
26e90 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
26ea0 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
26eb0 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
26ec0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
26ed0 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
26ee0 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
26ef0 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
26f00 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
26f10 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
26f20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
26f30 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
26f40 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
26f50 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
26f60 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
26f70 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
26f80 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
26f90 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
26fa0 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
26fb0 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
26fc0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
26fd0 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
26fe0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
26ff0 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
27000 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
27010 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
27020 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
27030 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
27040 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
27050 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
27060 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
27070 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
27080 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
27090 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
270a0 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
270b0 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
270c0 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
270d0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
270e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
270f0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
27100 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
27110 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
27120 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
27130 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
27140 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
27150 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
27160 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
27170 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
27180 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
27190 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
271a0 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
271b0 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
271c0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
271d0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
271e0 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c  ters.  Every SQL
271f0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
27200 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65  entation must be
27210 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
27220 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
27230 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
27240 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
27250 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
27260 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
27270 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
27280 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
27290 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c  other.  ^An appl
272a0 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69  ication may.** i
272b0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
272c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
272d0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
272e0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
272f0 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
27300 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
27310 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
27320 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
27330 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
27340 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
27350 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
27360 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
27370 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
27380 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
27390 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
273a0 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
273b0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
273c0 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
273d0 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
273e0 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
273f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
27400 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
27410 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
27420 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
27430 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
27440 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
27450 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
27460 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  Y]..**.** ^(The 
27470 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
27480 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
27490 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
274a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
274b0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
274c0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
274d0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
274e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
274f0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
27500 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 76 65 6e 74  *.** ^The sevent
27510 68 2c 20 65 69 67 68 74 68 20 61 6e 64 20 6e 69  h, eighth and ni
27520 6e 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  nth parameters, 
27530 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
27540 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
27550 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
27560 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
27570 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
27580 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
27590 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
275a0 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
275b0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
275c0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
275d0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
275e0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
275f0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
27600 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
27610 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
27620 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
27630 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
27640 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
27650 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
27660 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
27670 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
27680 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
27690 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
276a0 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
276b0 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
276c0 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
276d0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
276e0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
276f0 69 6e 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  iners for all th
27700 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
27710 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
27720 20 5e 49 66 20 74 68 65 20 74 65 6e 74 68 20 70   ^If the tenth p
27730 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
27740 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27750 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
27760 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
27770 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
27780 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
27790 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 20 74 68  on data point th
277a0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  at is invoked.**
277b0 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
277c0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
277d0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
277e0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
277f0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
27800 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
27810 73 65 73 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 64  ses.  .** ^The d
27820 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
27830 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
27840 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
27850 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
27860 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
27870 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
27880 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
27890 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
278a0 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
278b0 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
278c0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
278d0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
278e0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
278f0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
27900 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
27910 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
27920 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
27930 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
27940 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
27950 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
27960 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
27970 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
27980 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
27990 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
279a0 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
279b0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
279c0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
279d0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
279e0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
279f0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
27a00 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
27a10 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
27a20 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
27a30 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
27a40 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
27a50 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
27a60 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
27a70 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
27a80 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
27a90 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
27aa0 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
27ab0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
27ac0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
27ad0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
27ae0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
27af0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
27b00 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
27b10 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
27b20 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
27b30 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
27b40 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
27b50 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
27b60 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
27b70 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
27b80 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
27b90 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
27ba0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
27bb0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
27bc0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
27bd0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
27be0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
27bf0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
27c00 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
27c10 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
27c20 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
27c30 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
27c40 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
27c50 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
27c60 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
27c70 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
27c80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
27c90 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
27ca0 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
27cb0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
27cc0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
27cd0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
27ce0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
27cf0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
27d00 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
27d10 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
27d20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27d30 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
27d40 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
27d50 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
27d60 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
27d70 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
27d80 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ning..*/.int sql
27d90 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
27da0 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
27db0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
27dc0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
27dd0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
27de0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
27df0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
27e00 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
27e10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
27e20 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
27e30 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
27e40 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
27e50 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
27e60 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
27e70 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
27e80 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
27e90 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
27ea0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
27eb0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
27ec0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
27ed0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
27ee0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
27ef0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
27f00 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
27f10 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
27f20 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
27f30 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
27f40 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
27f50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
27f60 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
27f70 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
27f80 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
27f90 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  ext*).);.int sql
27fa0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
27fb0 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
27fc0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
27fd0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
27fe0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
27ff0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
28000 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
28010 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
28020 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
28030 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
28040 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
28050 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
28060 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
28070 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
28080 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
28090 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
280a0 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
280b0 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
280c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
280d0 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
280e0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
280f0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
28100 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
28110 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
28120 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
28130 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
28140 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
28150 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
28160 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
28170 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
28180 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
28190 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
281a0 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
281b0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
281c0 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
281d0 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
281e0 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
281f0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
28200 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
28210 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
28220 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
28230 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
28240 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
28250 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
28260 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
28270 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
28280 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
28290 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
282a0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
282b0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
282c0 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
282d0 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
282e0 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
282f0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
28300 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
28310 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
28320 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
28330 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
28340 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
28350 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
28360 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
28370 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
28380 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
28390 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
283a0 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
283b0 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
283c0 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
283d0 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
283e0 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
283f0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
28400 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
28410 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
28420 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
28430 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
28440 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
28450 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
28460 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
28470 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
28480 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
28490 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
284a0 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
284b0 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
284c0 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
284d0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
284e0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
284f0 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
28500 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
28510 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
28520 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
28530 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
28540 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
28550 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
28560 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
28570 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
28580 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
28590 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
285a0 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
285b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
285c0 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63  taining SQL Func
285d0 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56  tion Parameter V
285e0 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alues.**.** The 
285f0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
28600 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
28610 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
28620 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
28630 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
28640 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
28650 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
28660 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
28670 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
28680 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
28690 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
286a0 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
286b0 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
286c0 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
286d0 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
286e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
286f0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
28700 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
28710 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
28720 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
28730 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
28740 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
28750 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
28760 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 34 74 68  ates..** The 4th
28770 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
28780 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
28790 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
287a0 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
287b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
287c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
287d0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
287e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
287f0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
28800 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
28810 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
28820 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
28830 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
28840 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
28850 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
28860 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
28870 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
28880 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
28890 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
288a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
288b0 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
288c0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
288d0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
288e0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
288f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
28900 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
28910 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
28920 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
28930 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
28940 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
28950 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
28960 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
28970 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
28980 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75   that  these rou
28990 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e  tines take a sin
289a0 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73  gle [protected s
289b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
289c0 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ject.** pointer 
289d0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71  instead of a [sq
289e0 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69  lite3_stmt*] poi
289f0 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65  nter and an inte
28a00 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  ger column numbe
28a10 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
28a20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
28a30 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  16() interface e
28a40 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36  xtracts a UTF-16
28a50 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68   string.** in th
28a60 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72  e native byte-or
28a70 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20  der of the host 
28a80 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a  machine.  ^The.*
28a90 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  * sqlite3_value_
28aa0 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73  text16be() and s
28ab0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
28ac0 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63  t16le() interfac
28ad0 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54  es.** extract UT
28ae0 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20  F-16 strings as 
28af0 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c  big-endian and l
28b00 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73  ittle-endian res
28b10 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a  pectively..**.**
28b20 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76   ^(The sqlite3_v
28b30 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
28b40 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  e() interface at
28b50 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a  tempts to apply.
28b60 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e  ** numeric affin
28b70 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ity to the value
28b80 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68  .  This means th
28b90 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  at an attempt is
28ba0 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76  .** made to conv
28bb0 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f  ert the value to
28bc0 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66   an integer or f
28bd0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20  loating point.  
28be0 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e  If.** such a con
28bf0 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69  version is possi
28c00 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73  ble without loss
28c10 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20   of information 
28c20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72  (in other.** wor
28c30 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65  ds, if the value
28c40 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61   is a string tha
28c50 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e  t looks like a n
28c60 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74  umber).** then t
28c70 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  he conversion is
28c80 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68   performed.  Oth
28c90 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72  erwise no conver
28ca0 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20  sion occurs..** 
28cb0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  The [SQLITE_INTE
28cc0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20  GER | datatype] 
28cd0 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e  after conversion
28ce0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a   is returned.)^.
28cf0 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79  **.** Please pay
28d00 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65   particular atte
28d10 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63  ntion to the fac
28d20 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74  t that the point
28d30 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  er returned.** f
28d40 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  rom [sqlite3_val
28d50 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  ue_blob()], [sql
28d60 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
28d70 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
28d80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
28d90 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69  )] can be invali
28da0 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65  dated by a subse
28db0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  quent call to.**
28dc0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28dd0 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74  bytes()], [sqlit
28de0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
28df0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
28e00 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20  lue_text()],.** 
28e10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  or [sqlite3_valu
28e20 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a  e_text16()]..**.
28e30 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
28e40 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
28e50 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
28e60 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20  hread as.** the 
28e70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  SQL function tha
28e80 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b  t supplied the [
28e90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20  sqlite3_value*] 
28ea0 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63  parameters..*/.c
28eb0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
28ec0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
28ed0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
28ee0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
28ef0 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76  _bytes(sqlite3_v
28f00 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
28f10 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
28f20 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
28f30 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
28f40 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73  3_value_double(s
28f50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
28f60 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
28f70 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61  e_int(sqlite3_va
28f80 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69  lue*);.sqlite3_i
28f90 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c  nt64 sqlite3_val
28fa0 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  ue_int64(sqlite3
28fb0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
28fc0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
28fd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
28fe0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
28ff0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
29000 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
29010 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
29020 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
29030 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
29040 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
29050 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
29060 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
29070 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
29080 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
29090 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
290a0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
290b0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
290c0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
290d0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
290e0 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
290f0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
29100 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
29110 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  Context.**.** Im
29120 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
29130 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
29140 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
29150 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
29160 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
29170 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
29180 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
29190 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
291a0 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
291b0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
291c0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
291d0 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
291e0 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
291f0 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
29200 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
29210 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
29220 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
29230 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
29240 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
29250 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
29260 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
29270 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
29280 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
29290 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
292a0 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
292b0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
292c0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
292d0 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
292e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
292f0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
29300 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
29310 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
29320 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
29330 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
29340 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
29350 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
29360 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
29370 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
29380 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
29390 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
293a0 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
293b0 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
293c0 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
293d0 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
293e0 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
293f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
29400 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
29410 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
29420 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
29430 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
29440 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
29450 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
29460 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
29470 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
29480 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
29490 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
294a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
294b0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
294c0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
294d0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
294e0 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a  pointer if N is.
294f0 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20  ** less than or 
29500 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72  equal to zero or
29510 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
29520 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
29530 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
29540 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
29550 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
29560 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
29570 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
29580 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
29590 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
295a0 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
295b0 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
295c0 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
295d0 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
295e0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
295f0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
29600 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
29610 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
29620 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
29630 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
29640 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
29650 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
29660 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
29670 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
29680 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
29690 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
296a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
296b0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
296c0 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
296d0 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
296e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
296f0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
29700 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
29710 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
29720 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
29730 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
29740 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
29750 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
29760 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
29770 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
29780 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
29790 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
297a0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
297b0 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
297c0 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
297d0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
297e0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
297f0 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
29800 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
29810 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
29820 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
29830 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
29840 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
29850 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
29860 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
29870 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
29880 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
29890 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
298a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
298b0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
298c0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
298d0 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
298e0 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
298f0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
29900 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
29910 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
29920 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
29930 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
29940 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
29950 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
29960 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
29970 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
29980 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
29990 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
299a0 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
299b0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
299c0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
299d0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
299e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
299f0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
29a00 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
29a10 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
29a20 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
29a30 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
29a40 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
29a50 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
29a60 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
29a70 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
29a80 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
29a90 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
29aa0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
29ab0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
29ac0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
29ad0 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
29ae0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
29af0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
29b00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
29b10 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
29b20 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
29b30 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
29b40 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
29b50 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
29b60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
29b70 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
29b80 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
29b90 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
29ba0 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
29bb0 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
29bc0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
29bd0 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
29be0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f  .**.** The follo
29bf0 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f  wing two functio
29c00 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
29c10 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e  y scalar SQL fun
29c20 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
29c30 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
29c40 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
29c50 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
29c60 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
29c70 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
29c80 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
29c90 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
29ca0 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
29cb0 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
29cc0 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
29cd0 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
29ce0 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
29cf0 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
29d00 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20  ed. This may.** 
29d10 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61  be used, for exa
29d20 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72  mple, to add a r
29d30 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f  egular-expressio
29d40 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61  n matching scala
29d50 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  r.** function. T
29d60 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
29d70 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
29d80 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73  ar expression is
29d90 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
29da0 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
29db0 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76  d with the SQL v
29dc0 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
29dd0 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
29de0 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e  ssion.** pattern
29df0 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  .  The compiled 
29e00 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
29e10 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
29e20 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
29e30 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
29e40 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
29e50 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69   so that the ori
29e60 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74  ginal pattern st
29e70 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ring.** does not
29e80 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f   need to be reco
29e90 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69  mpiled on each i
29ea0 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  nvocation..**.**
29eb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
29ec0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
29ed0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
29ee0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
29ef0 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
29f00 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
29f10 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
29f20 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
29f30 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
29f40 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
29f50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
29f60 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
29f70 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20  ^If no metadata 
29f80 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a  has been ever.**
29f90 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68   been set for th
29fa0 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f  e Nth argument o
29fb0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20  f the function, 
29fc0 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72 65 73  or if the corres
29fd0 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  ponding.** funct
29fe0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61  ion parameter ha
29ff0 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20  s changed since 
2a000 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61  the meta-data wa
2a010 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73  s set,.** then s
2a020 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2a030 74 61 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  ta() returns a N
2a040 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
2a050 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a060 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
2a070 74 65 72 66 61 63 65 20 73 61 76 65 73 20 74 68  terface saves th
2a080 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f  e metadata.** po
2a090 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74 73 20  inted to by its 
2a0a0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  3rd parameter as
2a0b0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f   the metadata fo
2a0c0 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72  r the N-th.** ar
2a0d0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70  gument of the ap
2a0e0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2a0f0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62  d function.  Sub
2a100 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73  sequent.** calls
2a110 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f   to sqlite3_get_
2a120 61 75 78 64 61 74 61 28 29 20 6d 69 67 68 74 20  auxdata() might 
2a130 72 65 74 75 72 6e 20 74 68 69 73 20 64 61 74 61  return this data
2a140 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e  , if it has.** n
2a150 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ot been destroye
2a160 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  d..** ^If it is 
2a170 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65  not NULL, SQLite
2a180 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65   will invoke the
2a190 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66   destructor.** f
2a1a0 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79  unction given by
2a1b0 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2a1c0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  er to sqlite3_se
2a1d0 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a  t_auxdata() on.*
2a1e0 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 77  * the metadata w
2a1f0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
2a200 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70  nding function p
2a210 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73  arameter changes
2a220 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20  .** or when the 
2a230 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
2a240 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76  mpletes, whichev
2a250 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a  er comes first..
2a260 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  **.** SQLite is 
2a270 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65  free to call the
2a280 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20   destructor and 
2a290 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e  drop metadata on
2a2a0 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65   any.** paramete
2a2b0 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f  r of any functio
2a2c0 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20  n at any time.  
2a2d0 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e  ^The only guaran
2a2e0 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74  tee is that.** t
2a2f0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77 69  he destructor wi
2a300 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66  ll be called bef
2a310 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61 74 61  ore the metadata
2a320 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a   is dropped..**.
2a330 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65  ** ^(In practice
2a340 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72  , metadata is pr
2a350 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20  eserved between 
2a360 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66  function calls f
2a370 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  or.** expression
2a380 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74  s that are const
2a390 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ant at compile t
2a3a0 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64  ime. This includ
2a3b0 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61  es literal.** va
2a3c0 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65  lues and [parame
2a3d0 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  ters].)^.**.** T
2a3e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
2a3f0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
2a400 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
2a410 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
2a420 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2a430 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
2a440 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f  id *sqlite3_get_
2a450 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
2a460 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29  context*, int N)
2a470 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  ;.void sqlite3_s
2a480 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
2a490 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2a4a0 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
2a4b0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
2a4c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2a4d0 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
2a4e0 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
2a4f0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
2a500 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
2a510 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
2a520 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2a530 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
2a540 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
2a550 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
2a560 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2a570 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2a580 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
2a590 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
2a5a0 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
2a5b0 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
2a5c0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
2a5d0 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
2a5e0 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
2a5f0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
2a600 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
2a610 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
2a620 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
2a630 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
2a640 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
2a650 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
2a660 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
2a670 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
2a680 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
2a690 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
2a6a0 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2a6b0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
2a6c0 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
2a6d0 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
2a6e0 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
2a6f0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
2a700 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
2a710 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
2a720 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20  compilers.  See 
2a730 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f  ticket #2191..*/
2a740 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
2a750 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2a760 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
2a770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a780 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
2a790 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2a7a0 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
2a7b0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
2a7c0 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
2a7d0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
2a7e0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
2a7f0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
2a800 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
2a810 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
2a820 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2a830 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
2a840 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
2a850 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
2a860 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
2a870 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2a880 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
2a890 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a8a0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
2a8b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a8c0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
2a8d0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2a8e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
2a8f0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
2a900 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
2a910 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
2a920 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
2a930 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
2a940 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
2a950 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
2a960 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
2a970 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a980 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
2a990 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
2a9a0 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
2a9b0 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
2a9c0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
2a9d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2a9e0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
2a9f0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2aa00 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
2aa10 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
2aa20 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2aa30 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
2aa40 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
2aa50 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
2aa60 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
2aa70 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
2aa80 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
2aa90 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
2aaa0 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
2aab0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2aac0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
2aad0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
2aae0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
2aaf0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
2ab00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2ab10 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
2ab20 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
2ab30 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
2ab40 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
2ab50 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
2ab60 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
2ab70 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
2ab80 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
2ab90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
2aba0 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
2abb0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2abc0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
2abd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2abe0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2abf0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
2ac00 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
2ac10 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
2ac20 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
2ac30 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2ac40 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
2ac50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2ac60 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
2ac70 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
2ac80 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
2ac90 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
2aca0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
2acb0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
2acc0 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
2acd0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
2ace0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
2acf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2ad00 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
2ad10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2ad20 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
2ad30 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
2ad40 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
2ad50 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
2ad60 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
2ad70 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
2ad80 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2ad90 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
2ada0 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
2adb0 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
2adc0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
2add0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
2ade0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
2adf0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
2ae00 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2ae10 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2ae20 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2ae30 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2ae40 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2ae50 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
2ae60 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
2ae70 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
2ae80 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
2ae90 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
2aea0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
2aeb0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2aec0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2aed0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
2aee0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
2aef0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2af00 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
2af10 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
2af20 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
2af30 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
2af40 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
2af50 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
2af60 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
2af70 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
2af80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2af90 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
2afa0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2afb0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
2afc0 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
2afd0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
2afe0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
2aff0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
2b000 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
2b010 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
2b020 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
2b030 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
2b040 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
2b050 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
2b060 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
2b070 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2b080 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
2b090 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
2b0a0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
2b0b0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
2b0c0 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
2b0d0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
2b0e0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
2b0f0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
2b100 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
2b110 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
2b120 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
2b130 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
2b140 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
2b150 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2b160 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
2b170 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
2b180 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
2b190 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b1a0 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69  te3_result_toobi
2b1b0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  g() interface ca
2b1c0 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74  uses SQLite to t
2b1d0 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a  hrow an error.**
2b1e0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74   indicating that
2b1f0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
2b200 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f  B is too long to
2b210 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a   represent..**.*
2b220 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2b230 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e  esult_nomem() in
2b240 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
2b250 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
2b260 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
2b270 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
2b280 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
2b290 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
2b2a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b2b0 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
2b2c0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
2b2d0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
2b2e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2b2f0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2b300 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
2b310 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
2b320 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
2b330 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
2b340 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2b350 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
2b360 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2b370 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2b380 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2b390 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2b3a0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2b3b0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
2b3c0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
2b3d0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
2b3e0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
2b3f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2b400 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
2b410 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
2b420 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
2b430 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2b440 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2b450 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
2b460 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b470 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
2b480 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
2b490 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
2b4a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2b4b0 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
2b4c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2b4d0 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
2b4e0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
2b4f0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
2b500 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2b510 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2b520 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
2b530 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
2b540 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
2b550 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
2b560 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
2b570 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
2b580 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
2b590 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
2b5a0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53  pectively..** ^S
2b5b0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
2b5c0 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
2b5d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b5e0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
2b5f0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
2b600 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2b610 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
2b620 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  s..** ^If the 3r
2b630 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
2b640 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2b650 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2b660 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
2b670 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
2b680 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
2b690 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
2b6a0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
2b6b0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
2b6c0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
2b6d0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
2b6e0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2b6f0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2b700 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2b710 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
2b720 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
2b730 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
2b740 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
2b750 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
2b760 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
2b770 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
2b780 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b790 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
2b7a0 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  tion result..** 
2b7b0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
2b7c0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2b7d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2b7e0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2b7f0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2b800 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
2b810 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
2b820 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
2b830 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
2b840 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
2b850 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
2b860 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
2b870 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
2b880 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
2b890 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
2b8a0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
2b8b0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
2b8c0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
2b8d0 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
2b8e0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2b8f0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
2b900 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
2b910 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
2b920 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
2b930 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
2b940 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
2b950 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
2b960 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
2b970 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
2b980 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
2b990 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
2b9a0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
2b9b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
2b9c0 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
2b9d0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
2b9e0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
2b9f0 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2ba00 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2ba10 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2ba20 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
2ba30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2ba40 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
2ba50 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
2ba60 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
2ba70 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
2ba80 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
2ba90 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
2baa0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
2bab0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
2bac0 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
2bad0 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
2bae0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2baf0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
2bb00 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
2bb10 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
2bb20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2bb30 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2bb40 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
2bb50 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
2bb60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2bb70 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
2bb80 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
2bb90 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  eter.  ^The.** s
2bba0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2bbb0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
2bbc0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
2bbd0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2bbe0 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
2bbf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2bc00 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
2bc10 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
2bc20 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
2bc30 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
2bc40 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
2bc50 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
2bc60 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
2bc70 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65  .** ^A [protecte
2bc80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2bc90 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
2bca0 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
2bcb0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
2bcc0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2bcd0 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
2bce0 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
2bcf0 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
2bd00 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2bd10 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
2bd20 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
2bd30 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
2bd40 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2bd50 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68  called from with
2bd60 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74  in the different
2bd70 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20   thread.** than 
2bd80 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69  the one containi
2bd90 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ng the applicati
2bda0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2bdb0 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65  ion that receive
2bdc0 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  d.** the [sqlite
2bdd0 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74  3_context] point
2bde0 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  er, the results 
2bdf0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2be00 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
2be10 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
2be20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2be30 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2be40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2be50 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2be60 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
2be70 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
2be80 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
2be90 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2bea0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2beb0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
2bec0 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
2bed0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2bee0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2bef0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2bf00 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2bf10 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2bf20 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
2bf30 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
2bf40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2bf50 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
2bf60 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
2bf70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2bf80 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
2bf90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2bfa0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2bfb0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
2bfc0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2bfd0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
2bfe0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
2bff0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2c000 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2c010 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2c020 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
2c030 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2c040 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c050 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
2c060 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
2c070 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
2c080 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2c090 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2c0a0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt16(sqlite3_con
2c0b0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2c0c0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
2c0d0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
2c0e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2c0f0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
2c100 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2c110 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
2c120 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2c130 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2c140 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
2c150 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2c160 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
2c170 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2c180 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c190 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f  value(sqlite3_co
2c1a0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
2c1b0 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71  value*);.void sq
2c1c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
2c1d0 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  oblob(sqlite3_co
2c1e0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a  ntext*, int n);.
2c1f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c200 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c   Define New Coll
2c210 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a  ating Sequences.
2c220 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
2c230 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f  ctions add, remo
2c240 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20  ve, or modify a 
2c250 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f  [collation] asso
2c260 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74  ciated.** with t
2c270 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2c280 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
2c290 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
2c2a0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
2c2b0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2c2c0 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20   collation is a 
2c2d0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
2c2e0 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
2c2f0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61  te_collation() a
2c300 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nd sqlite3_creat
2c310 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2c320 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36  .** and a UTF-16
2c330 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76   string in nativ
2c340 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72  e byte order for
2c350 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c360 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a  collation16()..*
2c370 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d  * ^Collation nam
2c380 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20  es that compare 
2c390 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20  equal according 
2c3a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e  to [sqlite3_strn
2c3b0 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63  icmp()] are.** c
2c3c0 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20  onsidered to be 
2c3d0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a  the same name..*
2c3e0 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64  *.** ^(The third
2c3f0 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74   argument (eText
2c400 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  Rep) must be one
2c410 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74   of the constant
2c420 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  s:.** <ul>.** <l
2c430 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  i> [SQLITE_UTF8]
2c440 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
2c450 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c  E_UTF16LE],.** <
2c460 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
2c470 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6BE],.** <li> [S
2c480 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72  QLITE_UTF16], or
2c490 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
2c4a0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e  _UTF16_ALIGNED].
2c4b0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  .** </ul>)^.** ^
2c4c0 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  The eTextRep arg
2c4d0 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73  ument determines
2c4e0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
2c4f0 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a   strings passed.
2c500 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ** to the collat
2c510 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
2c520 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b  lback, xCallback
2c530 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
2c540 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51  E_UTF16] and [SQ
2c550 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2c560 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65  ED] values for e
2c570 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65  TextRep.** force
2c580 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55   strings to be U
2c590 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65  TF16 with native
2c5a0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20   byte order..** 
2c5b0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
2c5c0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
2c5d0 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66  e for eTextRep f
2c5e0 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f  orces strings to
2c5f0 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20   begin.** on an 
2c600 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73  even byte addres
2c610 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  s..**.** ^The fo
2c620 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70  urth argument, p
2c630 41 72 67 2c 20 69 73 20 61 20 61 70 70 6c 69 63  Arg, is a applic
2c640 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2c650 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
2c660 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20  d.** through as 
2c670 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2c680 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  nt to the collat
2c690 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
2c6a0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
2c6b0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2c6c0 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20  , xCallback, is 
2c6d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2c6e0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2c6f0 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c  ion..** ^Multipl
2c700 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2c710 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67  tions can be reg
2c720 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
2c730 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a  e same name but.
2c740 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ** with differen
2c750 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d  t eTextRep param
2c760 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65  eters and SQLite
2c770 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65   will use whiche
2c780 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ver.** function 
2c790 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61  requires the lea
2c7a0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
2c7b0 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e  a transformation
2c7c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61  ..** ^If the xCa
2c7d0 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
2c7e0 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
2c7f0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
2c800 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65  ion is.** delete
2c810 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f  d.  ^When all co
2c820 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2c830 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d  s having the sam
2c840 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74  e name are delet
2c850 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c  ed,.** that coll
2c860 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ation is no long
2c870 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  er usable..**.**
2c880 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20   ^The collating 
2c890 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
2c8a0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
2c8b0 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  h a copy of the 
2c8c0 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61  pArg .** applica
2c8d0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2c8e0 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73  r and with two s
2c8f0 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e  trings in the en
2c900 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
2c910 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74  .** by the eText
2c920 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Rep argument.  T
2c930 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2c940 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72  ction must retur
2c950 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  n an.** integer 
2c960 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65  that is negative
2c970 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74  , zero, or posit
2c980 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69  ive.** if the fi
2c990 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
2c9a0 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74  ss than, equal t
2c9b0 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
2c9c0 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a  an the second,.*
2c9d0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
2c9e0 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
2c9f0 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79  ction must alway
2ca00 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
2ca10 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e   answer.** given
2ca20 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
2ca30 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  .  If two or mor
2ca40 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2ca50 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74  tions are regist
2ca60 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73  ered.** to the s
2ca70 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ame collation na
2ca80 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 72  me (using differ
2ca90 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 6c  ent eTextRep val
2caa0 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a  ues) then all.**
2cab0 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 71   must give an eq
2cac0 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20  uivalent answer 
2cad0 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74  when invoked wit
2cae0 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72  h equivalent str
2caf0 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c  ings..** The col
2cb00 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2cb10 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f  must obey the fo
2cb20 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69  llowing properti
2cb30 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74  es for all.** st
2cb40 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20  rings A, B, and 
2cb50 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  C:.**.** <ol>.**
2cb60 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68   <li> If A==B th
2cb70 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e  en B==A..** <li>
2cb80 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d   If A==B and B==
2cb90 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20  C then A==C..** 
2cba0 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54  <li> If A&lt;B T
2cbb0 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c  HEN B&gt;A..** <
2cbc0 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e  li> If A&lt;B an
2cbd0 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26  d B&lt;C then A&
2cbe0 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  lt;C..** </ol>.*
2cbf0 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74  *.** If a collat
2cc00 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  ing function fai
2cc10 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62  ls any of the ab
2cc20 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20  ove constraints 
2cc30 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c  and that.** coll
2cc40 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
2cc50 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  s  registered an
2cc60 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  d used, then the
2cc70 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
2cc80 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ite.** is undefi
2cc90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2cca0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2ccb0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f  ollation_v2() wo
2ccc0 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
2ccd0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2cce0 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  n().** with the 
2ccf0 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68  addition that th
2cd00 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
2cd10 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
2cd20 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74  n pArg when.** t
2cd30 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2cd40 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
2cd50 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20  ..** ^Collating 
2cd60 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65  functions are de
2cd70 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 20  leted when they 
2cd80 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62  are overridden b
2cd90 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73  y later.** calls
2cda0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   to the collatio
2cdb0 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74  n creation funct
2cdc0 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65  ions or when the
2cdd0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
2cde0 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f  nnection] is clo
2cdf0 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  sed using [sqlit
2ce00 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a  e3_close()]..**.
2ce10 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79  ** ^The xDestroy
2ce20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e   callback is <u>
2ce30 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69  not</u> called i
2ce40 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65  f the .** sqlite
2ce50 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2ce60 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e  on_v2() function
2ce70 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61   fails.  Applica
2ce80 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b  tions that invok
2ce90 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65  e.** sqlite3_cre
2cea0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2ceb0 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  () with a non-NU
2cec0 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 75  LL xDestroy argu
2ced0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  ment should .** 
2cee0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
2cef0 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73   code and dispos
2cf00 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
2cf10 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
2cf20 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20  r.** themselves 
2cf30 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 65  rather than expe
2cf40 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20  cting SQLite to 
2cf50 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72  deal with it for
2cf60 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69   them..** This i
2cf70 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d  s different from
2cf80 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c   every other SQL
2cf90 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
2cfa0 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63  The inconsistenc
2cfb0 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75  y .** is unfortu
2cfc0 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20  nate but cannot 
2cfd0 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f  be changed witho
2cfe0 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b  ut breaking back
2cff0 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74  wards .** compat
2d000 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53  ibility..**.** S
2d010 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74  ee also:  [sqlit
2d020 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2d030 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ded()] and [sqli
2d040 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2d050 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e  eded16()]..*/.in
2d060 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2d070 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
2d080 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2d090 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
2d0a0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2d0b0 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
2d0c0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2d0d0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2d0e0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2d0f0 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c  oid*).);.int sql
2d100 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2d110 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
2d120 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2d130 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2d140 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2d150 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
2d160 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2d170 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2d180 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2d190 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
2d1a0 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
2d1b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
2d1c0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
2d1d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2d1e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d  const void *zNam
2d1f0 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  e,.  int eTextRe
2d200 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67  p, .  void *pArg
2d210 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72  ,.  int(*xCompar
2d220 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  e)(void*,int,con
2d230 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  st void*,int,con
2d240 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  st void*).);../*
2d250 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2d260 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43  llation Needed C
2d270 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
2d280 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20  To avoid having 
2d290 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20  to register all 
2d2a0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2d2b0 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 74  ces before a dat
2d2c0 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20  abase.** can be 
2d2d0 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63  used, a single c
2d2e0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2d2f0 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72   may be register
2d300 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2d310 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2d320 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b  ion] to be invok
2d330 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75  ed whenever an u
2d340 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
2d350 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69  on.** sequence i
2d360 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  s required..**.*
2d370 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  * ^If the functi
2d380 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 64  on is registered
2d390 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
2d3a0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2d3b0 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68  ded() API,.** th
2d3c0 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 20  en it is passed 
2d3d0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64  the names of und
2d3e0 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
2d3f0 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 74   sequences as st
2d400 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64  rings.** encoded
2d410 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73   in UTF-8. ^If s
2d420 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2d430 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 75  _needed16() is u
2d440 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  sed,.** the name
2d450 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  s are passed as 
2d460 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e  UTF-16 in machin
2d470 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
2d480 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  der..** ^A call 
2d490 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 69  to either functi
2d4a0 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 20  on replaces the 
2d4b0 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69  existing collati
2d4c0 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61  on-needed callba
2d4d0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e  ck..**.** ^(When
2d4e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   the callback is
2d4f0 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69   invoked, the fi
2d500 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73  rst argument pas
2d510 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a  sed is a copy.**
2d520 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
2d530 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2d540 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
2d550 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ded() or.** sqli
2d560 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2d570 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 73  eded16().  The s
2d580 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2d590 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  s the database.*
2d5a0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54  * connection.  T
2d5b0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2d5c0 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  t is one of [SQL
2d5d0 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
2d5e0 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20  TE_UTF16BE],.** 
2d5f0 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  or [SQLITE_UTF16
2d600 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20  LE], indicating 
2d610 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62  the most desirab
2d620 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63  le form of the c
2d630 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
2d640 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65  ence function re
2d650 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75  quired.  The fou
2d660 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
2d670 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2d680 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c  .** required col
2d690 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e  lation sequence.
2d6a0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c  )^.**.** The cal
2d6b0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
2d6c0 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 74  hould register t
2d6d0 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61  he desired colla
2d6e0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
2d6f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2d700 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  llation()], [sql
2d710 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2d720 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ation16()], or.*
2d730 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2d740 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
2d750 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2d760 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2d770 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ed(.  sqlite3*, 
2d780 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69  .  void*, .  voi
2d790 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2d7a0 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70  e3*,int eTextRep
2d7b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b  ,const char*).);
2d7c0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2d7d0 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
2d7e0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2d7f0 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29  void*,.  void(*)
2d800 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
2d810 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
2d820 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69  st void*).);..#i
2d830 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f  fdef SQLITE_HAS_
2d840 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CODEC./*.** Spec
2d850 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20  ify the key for 
2d860 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74  an encrypted dat
2d870 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75  abase.  This rou
2d880 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  tine should be.*
2d890 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61  * called right a
2d8a0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  fter sqlite3_ope
2d8b0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  n()..**.** The c
2d8c0 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  ode to implement
2d8d0 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74   this API is not
2d8e0 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68   available in th
2d8f0 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65  e public release
2d900 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  .** of SQLite..*
2d910 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65  /.int sqlite3_ke
2d920 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  y(.  sqlite3 *db
2d930 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
2d940 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2d950 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
2d960 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
2d970 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
2d980 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a    /* The key */.
2d990 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65  );../*.** Change
2d9a0 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f   the key on an o
2d9b0 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49  pen database.  I
2d9c0 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  f the current da
2d9d0 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a  tabase is not.**
2d9e0 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73   encrypted, this
2d9f0 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e   routine will en
2da00 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e  crypt it.  If pN
2da10 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30  ew==0 or nNew==0
2da20 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  , the.** databas
2da30 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a  e is decrypted..
2da40 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74  **.** The code t
2da50 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73  o implement this
2da60 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69   API is not avai
2da70 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62  lable in the pub
2da80 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f  lic release.** o
2da90 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74  f SQLite..*/.int
2daa0 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a   sqlite3_rekey(.
2dab0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
2dac0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2dad0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
2dae0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
2daf0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
2db00 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
2db10 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f  * The new key */
2db20 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  .);../*.** Speci
2db30 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f  fy the activatio
2db40 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20  n key for a SEE 
2db50 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73  database.  Unles
2db60 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c  s .** activated,
2db70 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45   none of the SEE
2db80 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77   routines will w
2db90 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ork..*/.void sql
2dba0 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65  ite3_activate_se
2dbb0 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e(.  const char 
2dbc0 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
2dbd0 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
2dbe0 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
2dbf0 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51  endif..#ifdef SQ
2dc00 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f  LITE_ENABLE_CERO
2dc10 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  D./*.** Specify 
2dc20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
2dc30 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64  ey for a CEROD d
2dc40 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
2dc50 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
2dc60 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f  none of the CERO
2dc70 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  D routines will 
2dc80 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  work..*/.void sq
2dc90 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 63  lite3_activate_c
2dca0 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20 63 68  erod(.  const ch
2dcb0 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20  ar *zPassPhrase 
2dcc0 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61         /* Activa
2dcd0 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29  tion phrase */.)
2dce0 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
2dcf0 43 41 50 49 33 52 45 46 3a 20 53 75 73 70 65 6e  CAPI3REF: Suspen
2dd00 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f 72 20  d Execution For 
2dd10 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a  A Short Time.**.
2dd20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  ** The sqlite3_s
2dd30 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f 6e 20  leep() function 
2dd40 63 61 75 73 65 73 20 74 68 65 20 63 75 72 72 65  causes the curre
2dd50 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73 75 73  nt thread to sus
2dd60 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a  pend execution.*
2dd70 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74 20 61  * for at least a
2dd80 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
2dd90 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66 69 65  seconds specifie
2dda0 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d 65 74  d in its paramet
2ddb0 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  er..**.** If the
2ddc0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
2ddd0 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f  m does not suppo
2dde0 72 74 20 73 6c 65 65 70 20 72 65 71 75 65 73 74  rt sleep request
2ddf0 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73  s with.** millis
2de00 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c  econd time resol
2de10 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ution, then the 
2de20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72 6f 75  time will be rou
2de30 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68  nded up to.** th
2de40 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f 6e 64  e nearest second
2de50 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  . The number of 
2de60 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
2de70 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a  sleep actually.*
2de80 2a 20 72 65 71 75 65 73 74 65 64 20 66 72 6f 6d  * requested from
2de90 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
2dea0 79 73 74 65 6d 20 69 73 20 72 65 74 75 72 6e 65  ystem is returne
2deb0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  d..**.** ^SQLite
2dec0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 69 73   implements this
2ded0 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 63 61   interface by ca
2dee0 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65 65 70  lling the xSleep
2def0 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  ().** method of 
2df00 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
2df10 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
2df20 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65 65 70  .  If the xSleep
2df30 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  () method.** of 
2df40 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
2df50 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  is not implement
2df60 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72  ed correctly, or
2df70 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
2df80 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e   at.** all, then
2df90 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
2dfa0 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29   sqlite3_sleep()
2dfb0 20 6d 61 79 20 64 65 76 69 61 74 65 20 66 72 6f   may deviate fro
2dfc0 6d 20 74 68 65 20 64 65 73 63 72 69 70 74 69 6f  m the descriptio
2dfd0 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72 65 76  n.** in the prev
2dfe0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 73 2e  ious paragraphs.
2dff0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2e000 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
2e010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2e020 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
2e030 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
2e040 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
2e050 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
2e060 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
2e070 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
2e080 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
2e090 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
2e0a0 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
2e0b0 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
2e0c0 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
2e0d0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
2e0e0 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
2e0f0 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
2e100 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
2e110 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
2e120 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
2e130 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
2e140 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2e150 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2e160 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
2e170 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
2e180 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
2e190 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
2e1a0 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
2e1b0 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
2e1c0 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
2e1d0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2e1e0 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
2e1f0 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
2e200 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
2e210 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
2e220 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
2e230 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
2e240 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2e250 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
2e260 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
2e270 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
2e280 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
2e290 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
2e2a0 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
2e2b0 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
2e2c0 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
2e2d0 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
2e2e0 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
2e2f0 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
2e300 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
2e310 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
2e320 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
2e330 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
2e340 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
2e350 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
2e360 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72   ^The [temp_stor
2e370 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2e380 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
2e390 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
2e3a0 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
2e3b0 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
2e3c0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2e3d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
2e3e0 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
2e3f0 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * the [temp_stor
2e400 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2e410 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
2e420 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
2e430 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
2e440 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
2e450 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
2e460 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2e470 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
2e480 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
2e490 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
2e4a0 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
2e4b0 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
2e4c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
2e4d0 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
2e4e0 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
2e4f0 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
2e500 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
2e510 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
2e520 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
2e530 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
2e540 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2e550 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
2e560 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
2e570 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  f the [temp_stor
2e580 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2e590 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
2e5a0 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oided..*/.SQLITE
2e5b0 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a 73 71  _EXTERN char *sq
2e5c0 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63  lite3_temp_direc
2e5d0 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tory;../*.** CAP
2e5e0 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f 72 20  I3REF: Test For 
2e5f0 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65  Auto-Commit Mode
2e600 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
2e610 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a  utocommit mode}.
2e620 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2e630 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
2e640 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  t() interface re
2e650 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f  turns non-zero o
2e660 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74 68 65  r.** zero if the
2e670 20 67 69 76 65 6e 20 64 61 74 61 62 61 73 65 20   given database 
2e680 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72  connection is or
2e690 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63   is not in autoc
2e6a0 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72  ommit mode,.** r
2e6b0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 5e 41  espectively.  ^A
2e6c0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2e6d0 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  s on by default.
2e6e0 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  .** ^Autocommit 
2e6f0 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c 65 64  mode is disabled
2e700 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20 73 74   by a [BEGIN] st
2e710 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74  atement..** ^Aut
2e720 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20  ocommit mode is 
2e730 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20 61 20  re-enabled by a 
2e740 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c  [COMMIT] or [ROL
2e750 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  LBACK]..**.** If
2e760 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f   certain kinds o
2e770 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72 20 6f  f errors occur o
2e780 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20 77 69  n a statement wi
2e790 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61  thin a multi-sta
2e7a0 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61  tement.** transa
2e7b0 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e  ction (errors in
2e7c0 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f  cluding [SQLITE_
2e7d0 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49  FULL], [SQLITE_I
2e7e0 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  OERR],.** [SQLIT
2e7f0 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54  E_NOMEM], [SQLIT
2e800 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51  E_BUSY], and [SQ
2e810 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 29  LITE_INTERRUPT])
2e820 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61   then the.** tra
2e830 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74 20 62  nsaction might b
2e840 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75  e rolled back au
2e850 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 54 68  tomatically.  Th
2e860 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a  e only way to.**
2e870 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74 68 65   find out whethe
2e880 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74  r SQLite automat
2e890 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
2e8a0 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2e8b0 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65  on after.** an e
2e8c0 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65 20 74  rror is to use t
2e8d0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
2e8e0 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72 20 74  .** If another t
2e8f0 68 72 65 61 64 20 63 68 61 6e 67 65 73 20 74 68  hread changes th
2e900 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61  e autocommit sta
2e910 74 75 73 20 6f 66 20 74 68 65 20 64 61 74 61 62  tus of the datab
2e920 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2e930 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72 6f 75  n while this rou
2e940 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c  tine is running,
2e950 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
2e960 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64   value.** is und
2e970 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
2e980 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
2e990 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b  ommit(sqlite3*);
2e9a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e9b0 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61 62  : Find The Datab
2e9c0 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20  ase Handle Of A 
2e9d0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2e9e0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  nt.**.** ^The sq
2e9f0 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20  lite3_db_handle 
2ea00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ea10 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
2ea20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
2ea30 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61  le.** to which a
2ea40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ea50 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20  ment] belongs.  
2ea60 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63  ^The [database c
2ea70 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65  onnection].** re
2ea80 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2ea90 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74  3_db_handle is t
2eaa0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
2eab0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
2eac0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66 69   that was the fi
2ead0 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
2eae0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
2eaf0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61  prepare_v2()] ca
2eb00 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69 61  ll (or its varia
2eb10 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75 73  nts) that was us
2eb20 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20  ed to.** create 
2eb30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  the statement in
2eb40 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
2eb50 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
2eb60 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28  lite3_db_handle(
2eb70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2eb80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2eb90 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70   Find the next p
2eba0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ebb0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
2ebc0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2ebd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2ebe0 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64 20   next [prepared 
2ebf0 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72  statement] after
2ec00 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69  .** pStmt associ
2ec10 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
2ec20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ec30 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53  on] pDb.  ^If pS
2ec40 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74  tmt is NULL.** t
2ec50 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61  hen this interfa
2ec60 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2ec70 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72 73  nter to the firs
2ec80 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
2ec90 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74  ment.** associat
2eca0 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74 61  ed with the data
2ecb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2ecc0 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65  pDb.  ^If no pre
2ecd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
2ece0 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68 65  ** satisfies the
2ecf0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74   conditions of t
2ed00 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20  his routine, it 
2ed10 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a  returns NULL..**
2ed20 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73  .** The [databas
2ed30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f  e connection] po
2ed40 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c  inter D in a cal
2ed50 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2ed60 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d  _next_stmt(D,S)]
2ed70 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20 61   must refer to a
2ed80 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a  n open database.
2ed90 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e  ** connection an
2eda0 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20  d in particular 
2edb0 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55  must not be a NU
2edc0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73  LL pointer..*/.s
2edd0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c  qlite3_stmt *sql
2ede0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73  ite3_next_stmt(s
2edf0 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71 6c  qlite3 *pDb, sql
2ee00 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2ee10 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ee20 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52  EF: Commit And R
2ee30 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63 61  ollback Notifica
2ee40 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
2ee50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ee60 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20  3_commit_hook() 
2ee70 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
2ee80 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a  ers a callback.*
2ee90 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  * function to be
2eea0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
2eeb0 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
2eec0 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d  is [COMMIT | com
2eed0 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79  mitted]..** ^Any
2eee0 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79   callback set by
2eef0 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c   a previous call
2ef00 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d   to sqlite3_comm
2ef10 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  it_hook().** for
2ef20 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2ef30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2ef40 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
2ef50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c  ^The sqlite3_rol
2ef60 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74  lback_hook() int
2ef70 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
2ef80 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
2ef90 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
2efa0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2efb0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2efc0 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c  [ROLLBACK | roll
2efd0 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e  ed back]..** ^An
2efe0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
2eff0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
2f000 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c  l to sqlite3_rol
2f010 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20  lback_hook().** 
2f020 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74  for the same dat
2f030 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f040 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a   is overridden..
2f050 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72 67  ** ^The pArg arg
2f060 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64 20  ument is passed 
2f070 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 63  through to the c
2f080 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20  allback..** ^If 
2f090 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20  the callback on 
2f0a0 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75  a commit hook fu
2f0b0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
2f0c0 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e  on-zero,.** then
2f0d0 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20 63   the commit is c
2f0e0 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
2f0f0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
2f100 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
2f110 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  mit_hook(D,C,P) 
2f120 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  and sqlite3_roll
2f130 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  back_hook(D,C,P)
2f140 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65   functions.** re
2f150 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75 6d  turn the P argum
2f160 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65  ent from the pre
2f170 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74 68  vious call of th
2f180 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a  e same function.
2f190 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b  ** on the same [
2f1a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2f1b0 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20  ion] D, or NULL 
2f1c0 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74  for.** the first
2f1d0 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20 66   call for each f
2f1e0 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a  unction on D..**
2f1f0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
2f200 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2f210 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
2f220 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
2f230 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
2f240 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2f250 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
2f260 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79  e callback.  Any
2f270 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d   actions.** to m
2f280 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2f290 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75  se connection mu
2f2a0 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20 75  st be deferred u
2f2b0 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a  ntil after the.*
2f2c0 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20  * completion of 
2f2d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2f2e0 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74  p()] call that t
2f2f0 72 69 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d  riggered the com
2f300 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61  mit.** or rollba
2f310 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66  ck hook in the f
2f320 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e  irst place..** N
2f330 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
2f340 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2f350 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
2f360 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
2f370 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
2f380 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
2f390 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
2f3a0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
2f3b0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
2f3c0 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67  .** ^Registering
2f3d0 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
2f3e0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
2f3f0 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57  llback..**.** ^W
2f400 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
2f410 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  ook callback rou
2f420 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
2f430 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a  o, the [COMMIT].
2f440 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ** operation is 
2f450 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69  allowed to conti
2f460 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e  nue normally.  ^
2f470 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  If the commit ho
2f480 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f  ok.** returns no
2f490 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
2f4a0 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e   [COMMIT] is con
2f4b0 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52  verted into a [R
2f4c0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68  OLLBACK]..** ^Th
2f4d0 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  e rollback hook 
2f4e0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20  is invoked on a 
2f4f0 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65  rollback that re
2f500 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d  sults from a com
2f510 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75  mit.** hook retu
2f520 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  rning non-zero, 
2f530 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64  just as it would
2f540 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68   be with any oth
2f550 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  er rollback..**.
2f560 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
2f570 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
2f580 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
2f590 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
2f5a0 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
2f5b0 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
2f5c0 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
2f5d0 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
2f5e0 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
2f5f0 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
2f600 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
2f610 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
2f620 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20   occur..** ^The 
2f630 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
2f640 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
2f650 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
2f660 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
2f670 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
2f680 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
2f690 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f6a0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
2f6b0 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
2f6c0 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
2f6d0 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
2f6e0 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
2f6f0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
2f700 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
2f710 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
2f720 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
2f730 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
2f740 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
2f750 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
2f760 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f770 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
2f780 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
2f790 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
2f7a0 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
2f7b0 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
2f7c0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
2f7d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
2f7e0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
2f7f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
2f800 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
2f810 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
2f820 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
2f830 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
2f840 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
2f850 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
2f860 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
2f870 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
2f880 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
2f890 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
2f8a0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2f8b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2f8c0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
2f8d0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2f8e0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
2f8f0 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
2f900 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
2f910 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20  hen a.** row is 
2f920 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
2f930 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
2f940 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2f950 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
2f960 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
2f970 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
2f980 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
2f990 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
2f9a0 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  ..** ^The second
2f9b0 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
2f9c0 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
2f9d0 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
2f9e0 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
2f9f0 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
2fa00 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
2fa10 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
2fa20 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
2fa30 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
2fa40 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  be invoked..** ^
2fa50 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
2fa60 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
2fa70 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
2fa80 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
2fa90 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
2faa0 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
2fab0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
2fac0 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
2fad0 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  * ^The final cal
2fae0 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
2faf0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
2fb00 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49  f the row..** ^I
2fb10 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
2fb20 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
2fb30 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74   the [rowid] aft
2fb40 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61  er the update ta
2fb50 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
2fb60 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f   ^(The update ho
2fb70 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
2fb80 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
2fb90 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
2fba0 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
2fbb0 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
2fbc0 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
2fbd0 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  uence).)^.**.** 
2fbe0 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  ^In the current 
2fbf0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
2fc00 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
2fc10 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ** is not invoke
2fc20 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69  d when duplicati
2fc30 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  on rows are dele
2fc40 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61  ted because of a
2fc50 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  n.** [ON CONFLIC
2fc60 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  T | ON CONFLICT 
2fc70 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e  REPLACE] clause.
2fc80 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70    ^Nor is the up
2fc90 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76  date hook.** inv
2fca0 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61  oked when rows a
2fcb0 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  re deleted using
2fcc0 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f   the [truncate o
2fcd0 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a  ptimization]..**
2fce0 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20   The exceptions 
2fcf0 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20  defined in this 
2fd00 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20  paragraph might 
2fd10 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
2fd20 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
2fd30 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
2fd40 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
2fd50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2fd60 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
2fd70 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
2fd80 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
2fd90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
2fda0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
2fdb0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e  update hook.  An
2fdc0 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
2fdd0 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
2fde0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
2fdf0 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
2fe00 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
2fe10 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
2fe20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2fe30 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
2fe40 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70  triggered the up
2fe50 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f  date hook..** No
2fe60 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
2fe70 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2fe80 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
2fe90 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
2fea0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
2feb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
2fec0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
2fed0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
2fee0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
2fef0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ff00 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c  update_hook(D,C,
2ff10 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  P) function.** r
2ff20 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67  eturns the P arg
2ff30 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
2ff40 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20  revious call.** 
2ff50 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
2ff60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2ff70 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
2ff80 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
2ff90 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53  ll on D..**.** S
2ffa0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
2ffb0 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
2ffc0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2ffd0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
2ffe0 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ].** interfaces.
2fff0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
30000 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
30010 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
30020 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
30030 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
30040 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
30050 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
30060 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
30070 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
30080 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
30090 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20   Pager Cache.** 
300a0 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
300b0 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e  d cache}.**.** ^
300c0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
300d0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
300e0 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
300f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
30100 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
30110 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
30120 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
30130 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
30140 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
30150 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
30160 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
30170 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
30180 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
30190 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
301a0 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
301b0 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
301c0 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
301d0 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
301e0 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
301f0 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
30200 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
30210 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
30220 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
30230 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
30240 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
30250 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
30260 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
30270 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
30280 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
30290 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
302a0 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
302b0 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
302c0 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
302d0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
302e0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
302f0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
30300 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
30310 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
30320 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
30330 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30340 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
30350 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
30360 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
30370 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
30380 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
30390 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
303a0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
303b0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
303c0 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
303d0 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
303e0 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
303f0 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
30400 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
30410 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
30420 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
30430 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
30440 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
30450 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
30460 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
30470 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
30480 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
30490 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
304a0 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
304b0 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
304c0 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
304d0 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  licitly..**.** S
304e0 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74  ee Also:  [SQLit
304f0 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d  e Shared-Cache M
30500 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ode].*/.int sqli
30510 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
30520 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
30530 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
30540 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
30550 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
30560 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
30570 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
30580 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
30590 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
305a0 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
305b0 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
305c0 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
305d0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
305e0 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
305f0 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
30600 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
30610 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
30620 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
30630 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
30640 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
30650 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
30660 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
30670 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
30680 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
30690 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
306a0 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
306b0 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
306c0 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
306d0 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
306e0 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
306f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30700 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
30710 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f   routine is a no
30720 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65  -op returning ze
30730 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  ro.** if SQLite 
30740 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20  is not compiled 
30750 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  with [SQLITE_ENA
30760 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
30770 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  EMENT]..*/.int s
30780 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d  qlite3_release_m
30790 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  emory(int);../*.
307a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70  ** CAPI3REF: Imp
307b0 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48  ose A Limit On H
307c0 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e  eap Size.**.** ^
307d0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  The sqlite3_soft
307e0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
307f0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 61  interface sets a
30800 6e 64 2f 6f 72 20 71 75 65 72 69 65 73 20 74 68  nd/or queries th
30810 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20  e.** soft limit 
30820 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  on the amount of
30830 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61   heap memory tha
30840 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74  t may be allocat
30850 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a  ed by SQLite..**
30860 20 5e 53 51 4c 69 74 65 20 73 74 72 69 76 65 73   ^SQLite strives
30870 20 74 6f 20 6b 65 65 70 20 68 65 61 70 20 6d 65   to keep heap me
30880 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e  mory utilization
30890 20 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20   below the soft 
308a0 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79  heap.** limit by
308b0 20 72 65 64 75 63 69 6e 67 20 74 68 65 20 6e 75   reducing the nu
308c0 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 68 65  mber of pages he
308d0 6c 64 20 69 6e 20 74 68 65 20 70 61 67 65 20 63  ld in the page c
308e0 61 63 68 65 0a 2a 2a 20 61 73 20 68 65 61 70 20  ache.** as heap 
308f0 6d 65 6d 6f 72 79 20 75 73 61 67 65 73 20 61 70  memory usages ap
30900 70 72 6f 61 63 68 65 73 20 74 68 65 20 6c 69 6d  proaches the lim
30910 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74  it..** ^The soft
30920 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 22   heap limit is "
30930 73 6f 66 74 22 20 62 65 63 61 75 73 65 20 65 76  soft" because ev
30940 65 6e 20 74 68 6f 75 67 68 20 53 51 4c 69 74 65  en though SQLite
30950 20 73 74 72 69 76 65 73 20 74 6f 20 73 74 61 79   strives to stay
30960 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c 69  .** below the li
30970 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20 65 78 63  mit, it will exc
30980 65 65 64 20 74 68 65 20 6c 69 6d 69 74 20 72 61  eed the limit ra
30990 74 68 65 72 20 74 68 61 6e 20 67 65 6e 65 72 61  ther than genera
309a0 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45  te.** an [SQLITE
309b0 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20  _NOMEM] error.  
309c0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
309d0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
309e0 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64 76 69 73  mit .** is advis
309f0 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ory only..**.** 
30a00 5e 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  ^The return valu
30a10 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73  e from sqlite3_s
30a20 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
30a30 28 29 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  () is the size o
30a40 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65  f.** the soft he
30a50 61 70 20 6c 69 6d 69 74 20 70 72 69 6f 72 20 74  ap limit prior t
30a60 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e 49 66  o the call.  ^If
30a70 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20   the argument N 
30a80 69 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74  is negative.** t
30a90 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69 73  hen no change is
30aa0 20 6d 61 64 65 20 74 6f 20 74 68 65 20 73 6f 66   made to the sof
30ab0 74 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 48  t heap limit.  H
30ac0 65 6e 63 65 2c 20 74 68 65 20 63 75 72 72 65 6e  ence, the curren
30ad0 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65  t.** size of the
30ae0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
30af0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
30b00 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a  ed by invoking.*
30b10 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  * sqlite3_soft_h
30b20 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 77 69  eap_limit64() wi
30b30 74 68 20 61 20 6e 65 67 61 74 69 76 65 20 61 72  th a negative ar
30b40 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gument..**.** ^I
30b50 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e  f the argument N
30b60 20 69 73 20 7a 65 72 6f 20 74 68 65 6e 20 74 68   is zero then th
30b70 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
30b80 74 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a  t is disabled..*
30b90 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74 20  *.** ^(The soft 
30ba0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f  heap limit is no
30bb0 74 20 65 6e 66 6f 72 63 65 64 20 69 6e 20 74 68  t enforced in th
30bc0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
30bd0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f  entation.** if o
30be0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f  ne or more of fo
30bf0 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f  llowing conditio
30c00 6e 73 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a  ns are true:.**.
30c10 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
30c20 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  The soft heap li
30c30 6d 69 74 20 69 73 20 73 65 74 20 74 6f 20 7a 65  mit is set to ze
30c40 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f  ro..** <li> Memo
30c50 72 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 73  ry accounting is
30c60 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
30c70 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
30c80 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71   the.**      [sq
30c90 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
30ca0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
30cb0 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61  STATUS],...) sta
30cc0 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61  rt-time option a
30cd0 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 5b  nd.**      the [
30ce0 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
30cf0 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c  EMSTATUS] compil
30d00 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
30d10 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e  * <li> An altern
30d20 61 74 69 76 65 20 70 61 67 65 20 63 61 63 68 65  ative page cache
30d30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
30d40 69 73 20 73 70 65 63 69 66 65 64 20 75 73 69 6e  is specifed usin
30d50 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74  g.**      [sqlit
30d60 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
30d70 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
30d80 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20  ],...)..** <li> 
30d90 54 68 65 20 70 61 67 65 20 63 61 63 68 65 20 61  The page cache a
30da0 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20 69 74  llocates from it
30db0 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f  s own memory poo
30dc0 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20  l supplied.**   
30dd0 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63     by [sqlite3_c
30de0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
30df0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
30e00 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20 74 68 61  ,...) rather tha
30e10 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20 74  n.**      from t
30e20 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c  he heap..** </ul
30e30 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e  >)^.**.** Beginn
30e40 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20  ing with SQLite 
30e50 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74  version 3.7.3, t
30e60 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
30e70 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a  it is enforced.*
30e80 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
30e90 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
30ea0 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
30eb0 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
30ec0 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  ENT].** compile-
30ed0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 69  time option is i
30ee0 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b 53  nvoked.  With [S
30ef0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
30f00 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c  ORY_MANAGEMENT],
30f10 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61  .** the soft hea
30f20 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72  p limit is enfor
30f30 63 65 64 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d  ced on every mem
30f40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20  ory allocation. 
30f50 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c   Without.** [SQL
30f60 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
30f70 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74  Y_MANAGEMENT], t
30f80 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
30f90 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72  it is only enfor
30fa0 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f  ced.** when memo
30fb0 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20  ry is allocated 
30fc0 62 79 20 74 68 65 20 70 61 67 65 20 63 61 63 68  by the page cach
30fd0 65 2e 20 20 54 65 73 74 69 6e 67 20 73 75 67 67  e.  Testing sugg
30fe0 65 73 74 73 20 74 68 61 74 20 62 65 63 61 75 73  ests that becaus
30ff0 65 0a 2a 2a 20 74 68 65 20 70 61 67 65 20 63 61  e.** the page ca
31000 63 68 65 20 69 73 20 74 68 65 20 70 72 65 64 6f  che is the predo
31010 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75 73  minate memory us
31020 65 72 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f  er in SQLite, mo
31030 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
31040 6e 73 20 77 69 6c 6c 20 61 63 68 69 65 76 65 20  ns will achieve 
31050 61 64 65 71 75 61 74 65 20 73 6f 66 74 20 68 65  adequate soft he
31060 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65  ap limit enforce
31070 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20  ment without.** 
31080 74 68 65 20 75 73 65 20 6f 66 20 5b 53 51 4c 49  the use of [SQLI
31090 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
310a0 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a  _MANAGEMENT]..**
310b0 0a 2a 2a 20 54 68 65 20 63 69 72 63 75 6d 73 74  .** The circumst
310c0 61 6e 63 65 73 20 75 6e 64 65 72 20 77 68 69 63  ances under whic
310d0 68 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e  h SQLite will en
310e0 66 6f 72 63 65 20 74 68 65 20 73 6f 66 74 20 68  force the soft h
310f0 65 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a  eap limit may.**
31100 20 63 68 61 6e 67 65 73 20 69 6e 20 66 75 74 75   changes in futu
31110 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
31120 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  QLite..*/.sqlite
31130 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
31140 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
31150 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  4(sqlite3_int64 
31160 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
31170 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
31180 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20  Soft Heap Limit 
31190 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50  Interface.** DEP
311a0 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
311b0 69 73 20 69 73 20 61 20 64 65 70 72 65 63 61 74  is is a deprecat
311c0 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
311d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  e [sqlite3_soft_
311e0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
311f0 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  ** interface.  T
31200 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70  his routine is p
31210 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69 73 74  rovided for hist
31220 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
31230 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41  lity.** only.  A
31240 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  ll new applicati
31250 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ons should use t
31260 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
31270 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
31280 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61  ()] interface ra
31290 74 68 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f  ther than this o
312a0 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45  ne..*/.SQLITE_DE
312b0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
312c0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
312d0 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a  limit(int N);...
312e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
312f0 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61  Extract Metadata
31300 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20   About A Column 
31310 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a  Of A Table.**.**
31320 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
31330 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20  eturns metadata 
31340 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63  about a specific
31350 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65   column of a spe
31360 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73  cific.** databas
31370 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62  e table accessib
31380 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61  le using the [da
31390 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
313a0 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73  n] handle.** pas
313b0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
313c0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
313d0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  nt..**.** ^The c
313e0 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66  olumn is identif
313f0 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ied by the secon
31400 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  d, third and fou
31410 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
31420 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69  o.** this functi
31430 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  on. ^The second 
31440 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74  parameter is eit
31450 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  her the name of 
31460 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
31470 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74  (i.e. "main", "t
31480 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61  emp", or an atta
31490 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63  ched database) c
314a0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70  ontaining the sp
314b0 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65  ecified.** table
314c0 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74   or NULL. ^If it
314d0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61   is NULL, then a
314e0 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ll attached data
314f0 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68  bases are search
31500 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61  ed.** for the ta
31510 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61  ble using the sa
31520 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65  me algorithm use
31530 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
31540 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72  e engine to.** r
31550 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69  esolve unqualifi
31560 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e  ed table referen
31570 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ces..**.** ^The 
31580 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
31590 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
315a0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  his function are
315b0 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63   the table and c
315c0 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66  olumn.** name of
315d0 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
315e0 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  umn, respectivel
315f0 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68  y. Neither of th
31600 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  ese parameters.*
31610 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a  * may be NULL..*
31620 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69  *.** ^Metadata i
31630 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72  s returned by wr
31640 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d  iting to the mem
31650 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61  ory locations pa
31660 73 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a  ssed as the 5th.
31670 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  ** and subsequen
31680 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
31690 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  this function. ^
316a0 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67  Any of these arg
316b0 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a  uments may be.**
316c0 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20   NULL, in which 
316d0 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70  case the corresp
316e0 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f  onding element o
316f0 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d  f metadata is om
31700 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  itted..**.** ^(<
31710 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
31720 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
31730 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61  >.** <tr><th> Pa
31740 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74  rameter <th> Out
31750 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  put<br>Type <th>
31760 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a    Description.**
31770 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68  .** <tr><td> 5th
31780 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72   <td> const char
31790 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65  * <td> Data type
317a0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68  .** <tr><td> 6th
317b0 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72   <td> const char
317c0 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64  * <td> Name of d
317d0 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e  efault collation
317e0 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72   sequence.** <tr
317f0 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69  ><td> 7th <td> i
31800 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20  nt         <td> 
31810 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68  True if column h
31820 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  as a NOT NULL co
31830 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e  nstraint.** <tr>
31840 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e  <td> 8th <td> in
31850 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
31860 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
31870 20 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49   part of the PRI
31880 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e  MARY KEY.** <tr>
31890 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e  <td> 9th <td> in
318a0 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
318b0 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73  rue if column is
318c0 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d   [AUTOINCREMENT]
318d0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
318e0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
318f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
31900 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  y pointed to by 
31910 74 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f  the character po
31920 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
31930 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61  for the.** decla
31940 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20  ration type and 
31950 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
31960 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79  ce is valid only
31970 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a   until the next.
31980 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53  ** call to any S
31990 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69  QLite API functi
319a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
319b0 65 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c  e specified tabl
319c0 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20  e is actually a 
319d0 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20  view, an [error 
319e0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
319f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
31a00 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d   specified colum
31a10 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f  n is "rowid", "o
31a20 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22  id" or "_rowid_"
31a30 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45   and an.** [INTE
31a40 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
31a50 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e   column has been
31a60 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
31a70 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  ared, then the o
31a80 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74  utput.** paramet
31a90 65 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20  ers are set for 
31aa0 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64  the explicitly d
31ab0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20  eclared column. 
31ac0 5e 28 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f  ^(If there is no
31ad0 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64  .** explicitly d
31ae0 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52  eclared [INTEGER
31af0 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f   PRIMARY KEY] co
31b00 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f  lumn, then the o
31b10 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74  utput.** paramet
31b20 65 72 73 20 61 72 65 20 73 65 74 20 61 73 20 66  ers are set as f
31b30 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ollows:.**.** <p
31b40 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20  re>.**     data 
31b50 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a  type: "INTEGER".
31b60 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e  **     collation
31b70 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41   sequence: "BINA
31b80 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e  RY".**     not n
31b90 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72  ull: 0.**     pr
31ba0 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20  imary key: 1.** 
31bb0 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65      auto increme
31bc0 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29  nt: 0.** </pre>)
31bd0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66  ^.**.** ^(This f
31be0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64  unction may load
31bf0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68   one or more sch
31c00 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61  emas from databa
31c10 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a  se files. If an.
31c20 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  ** error occurs 
31c30 64 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63  during this proc
31c40 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72  ess, or if the r
31c50 65 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f  equested table o
31c60 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e  r column.** cann
31c70 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20  ot be found, an 
31c80 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
31c90 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20  returned and an 
31ca0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65  error message le
31cb0 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61  ft.** in the [da
31cc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31cd0 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65  n] (to be retrie
31ce0 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65  ved using sqlite
31cf0 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a  3_errmsg()).)^.*
31d00 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69  *.** ^This API i
31d10 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
31d20 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
31d30 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
31d40 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
31d50 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
31d60 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
31d70 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64  ocessor symbol d
31d80 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73  efined..*/.int s
31d90 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c  qlite3_table_col
31da0 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20  umn_metadata(.  
31db0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
31dc0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43              /* C
31dd0 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65  onnection handle
31de0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
31df0 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
31e00 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61    /* Database na
31e10 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20  me or NULL */.  
31e20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62  const char *zTab
31e30 6c 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54  leName,     /* T
31e40 61 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  able name */.  c
31e50 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75  onst char *zColu
31e60 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f  mnName,    /* Co
31e70 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63  lumn name */.  c
31e80 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61  har const **pzDa
31e90 74 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55  taType,    /* OU
31ea0 54 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64  TPUT: Declared d
31eb0 61 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68  ata type */.  ch
31ec0 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c  ar const **pzCol
31ed0 6c 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54  lSeq,     /* OUT
31ee0 50 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73  PUT: Collation s
31ef0 65 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a  equence name */.
31f00 20 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c    int *pNotNull,
31f10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
31f20 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66   OUTPUT: True if
31f30 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72   NOT NULL constr
31f40 61 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20  aint exists */. 
31f50 20 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65   int *pPrimaryKe
31f60 79 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  y,           /* 
31f70 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
31f80 63 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50  column part of P
31f90 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74  K */.  int *pAut
31fa0 6f 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20  oinc            
31fb0 20 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72     /* OUTPUT: Tr
31fc0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
31fd0 61 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a  auto-increment *
31fe0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
31ff0 33 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78  3REF: Load An Ex
32000 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  tension.**.** ^T
32010 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f  his interface lo
32020 61 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78  ads an SQLite ex
32030 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
32040 66 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66  from the named f
32050 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ile..**.** ^The 
32060 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
32070 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61  ension() interfa
32080 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c  ce attempts to l
32090 6f 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65  oad an.** SQLite
320a0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61   extension libra
320b0 72 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20  ry contained in 
320c0 74 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a  the file zFile..
320d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79  **.** ^The entry
320e0 20 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e   point is zProc.
320f0 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62  .** ^zProc may b
32100 65 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61  e 0, in which ca
32110 73 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  se the name of t
32120 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a  he entry point.*
32130 2a 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73  * defaults to "s
32140 71 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e  qlite3_extension
32150 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20  _init"..** ^The 
32160 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
32170 65 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61  ension() interfa
32180 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ce returns.** [S
32190 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
321a0 63 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45  cess and [SQLITE
321b0 5f 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74  _ERROR] if somet
321c0 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
321d0 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
321e0 20 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72   occurs and pzEr
321f0 72 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74  rMsg is not 0, t
32200 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  hen the.** [sqli
32210 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
32220 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  on()] interface 
32230 73 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f  shall attempt to
32240 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d  .** fill *pzErrM
32250 73 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65  sg with error me
32260 73 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65  ssage text store
32270 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f  d in memory.** o
32280 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
32290 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
322a0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   The calling fun
322b0 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ction.** should 
322c0 66 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79  free this memory
322d0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
322e0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
322f0 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c  .** ^Extension l
32300 6f 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65  oading must be e
32310 6e 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20  nabled using.** 
32320 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
32330 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
32340 5d 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ] prior to calli
32350 6e 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20  ng this API,.** 
32360 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
32370 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72  or will be retur
32380 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ned..**.** See a
32390 6c 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78  lso the [load_ex
323a0 74 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66 75  tension() SQL fu
323b0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20  nction]..*/.int 
323c0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
323d0 65 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  ension(.  sqlite
323e0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
323f0 2f 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65  /* Load the exte
32400 6e 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20  nsion into this 
32410 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32420 69 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ion */.  const c
32430 68 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f  har *zFile,    /
32440 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68  * Name of the sh
32450 61 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e  ared library con
32460 74 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f  taining extensio
32470 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
32480 72 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20  r *zProc,    /* 
32490 45 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65  Entry point.  De
324a0 72 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65  rived from zFile
324b0 20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20   if 0 */.  char 
324c0 2a 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20  **pzErrMsg      
324d0 20 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65   /* Put error me
324e0 73 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f  ssage here if no
324f0 74 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  t 0 */.);../*.**
32500 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
32510 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
32520 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a  ension Loading.*
32530 2a 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20  *.** ^So as not 
32540 74 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79  to open security
32550 20 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20   holes in older 
32560 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
32570 74 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61  t are.** unprepa
32580 72 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68  red to deal with
32590 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
325a0 6e 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61  ng, and as a mea
325b0 6e 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a  ns of disabling.
325c0 2a 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  ** extension loa
325d0 64 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75  ding while evalu
325e0 61 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72  ating user-enter
325f0 65 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c  ed SQL, the foll
32600 6f 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20  owing API.** is 
32610 70 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e  provided to turn
32620 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
32630 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
32640 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64  mechanism on and
32650 20 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74   off..**.** ^Ext
32660 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69  ension loading i
32670 73 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74  s off by default
32680 2e 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38  . See ticket #18
32690 36 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65  63..** ^Call the
326a0 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f   sqlite3_enable_
326b0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
326c0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e   routine with on
326d0 6f 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72  off==1.** to tur
326e0 6e 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  n extension load
326f0 69 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20  ing on and call 
32700 69 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30  it with onoff==0
32710 20 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62   to turn.** it b
32720 61 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a  ack off again..*
32730 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e  /.int sqlite3_en
32740 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
32750 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c  ion(sqlite3 *db,
32760 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a   int onoff);../*
32770 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
32780 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64  tomatically Load
32790 20 53 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b   Statically Link
327a0 65 64 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a  ed Extensions.**
327b0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
327c0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ace causes the x
327d0 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 66 75 6e  EntryPoint() fun
327e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f  ction to be invo
327f0 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ked for.** each 
32800 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f  new [database co
32810 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 69  nnection] that i
32820 73 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20  s created.  The 
32830 69 64 65 61 20 68 65 72 65 20 69 73 20 74 68 61  idea here is tha
32840 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74  t.** xEntryPoint
32850 28 29 20 69 73 20 74 68 65 20 65 6e 74 72 79 20  () is the entry 
32860 70 6f 69 6e 74 20 66 6f 72 20 61 20 73 74 61 74  point for a stat
32870 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51  ically linked SQ
32880 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a  Lite extension.*
32890 2a 20 74 68 61 74 20 69 73 20 74 6f 20 62 65 20  * that is to be 
328a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f  automatically lo
328b0 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65  aded into all ne
328c0 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
328d0 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ctions..**.** ^(
328e0 45 76 65 6e 20 74 68 6f 75 67 68 20 74 68 65 20  Even though the 
328f0 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79  function prototy
32900 70 65 20 73 68 6f 77 73 20 74 68 61 74 20 78 45  pe shows that xE
32910 6e 74 72 79 50 6f 69 6e 74 28 29 20 74 61 6b 65  ntryPoint() take
32920 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74  s.** no argument
32930 73 20 61 6e 64 20 72 65 74 75 72 6e 73 20 76 6f  s and returns vo
32940 69 64 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  id, SQLite invok
32950 65 73 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  es xEntryPoint()
32960 20 77 69 74 68 20 74 68 72 65 65 0a 2a 2a 20 61   with three.** a
32970 72 67 75 6d 65 6e 74 73 20 61 6e 64 20 65 78 70  rguments and exp
32980 65 63 74 73 20 61 6e 64 20 69 6e 74 65 67 65 72  ects and integer
32990 20 72 65 73 75 6c 74 20 61 73 20 69 66 20 74 68   result as if th
329a0 65 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74  e signature of t
329b0 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e  he.** entry poin
329c0 74 20 77 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f  t where as follo
329d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
329e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26  quote><pre>.** &
329f0 6e 62 73 70 3b 20 20 69 6e 74 20 78 45 6e 74 72  nbsp;  int xEntr
32a00 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70  yPoint(.** &nbsp
32a10 3b 20 20 20 20 73 71 6c 69 74 65 33 20 2a 64 62  ;    sqlite3 *db
32a20 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63  ,.** &nbsp;    c
32a30 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 45 72  onst char **pzEr
32a40 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20  rMsg,.** &nbsp; 
32a50 20 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20     const struct 
32a60 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
32a70 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20  ines *pThunk.** 
32a80 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f  &nbsp;  );.** </
32a90 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
32aa0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  >)^.**.** If the
32ab0 20 78 45 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75   xEntryPoint rou
32ac0 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65 72 73 20  tine encounters 
32ad0 61 6e 20 65 72 72 6f 72 2c 20 69 74 20 73 68 6f  an error, it sho
32ae0 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d  uld make *pzErrM
32af0 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  sg.** point to a
32b00 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72  n appropriate er
32b10 72 6f 72 20 6d 65 73 73 61 67 65 20 28 6f 62 74  ror message (obt
32b20 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
32b30 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a  te3_mprintf()]).
32b40 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e  ** and return an
32b50 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
32b60 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c  ror code].  ^SQL
32b70 69 74 65 20 65 6e 73 75 72 65 73 20 74 68 61 74  ite ensures that
32b80 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73   *pzErrMsg.** is
32b90 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c   NULL before cal
32ba0 6c 69 6e 67 20 74 68 65 20 78 45 6e 74 72 79 50  ling the xEntryP
32bb0 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c 69 74 65  oint().  ^SQLite
32bc0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
32bd0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
32be0 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67 20 61 66   on *pzErrMsg af
32bf0 74 65 72 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  ter xEntryPoint(
32c00 29 20 72 65 74 75 72 6e 73 2e 20 20 5e 49 66 20  ) returns.  ^If 
32c10 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69  any.** xEntryPoi
32c20 6e 74 28 29 20 72 65 74 75 72 6e 73 20 61 6e 20  nt() returns an 
32c30 65 72 72 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69  error, the [sqli
32c40 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
32c50 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c  lite3_open16()],
32c60 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
32c70 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20  open_v2()] call 
32c80 74 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68  that provoked th
32c90 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  e xEntryPoint() 
32ca0 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  will fail..**.**
32cb0 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
32cc0 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
32cd0 28 58 29 20 77 69 74 68 20 61 6e 20 65 6e 74 72  (X) with an entr
32ce0 79 20 70 6f 69 6e 74 20 58 20 74 68 61 74 20 69  y point X that i
32cf0 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20  s already.** on 
32d00 74 68 65 20 6c 69 73 74 20 6f 66 20 61 75 74 6f  the list of auto
32d10 6d 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73  matic extensions
32d20 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
32d30 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20  o-op. ^No entry 
32d40 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65  point.** will be
32d50 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61   called more tha
32d60 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  n once for each 
32d70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32d80 69 6f 6e 20 74 68 61 74 20 69 73 20 6f 70 65 6e  ion that is open
32d90 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ed..**.** See al
32da0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  so: [sqlite3_res
32db0 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  et_auto_extensio
32dc0 6e 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  n()]..*/.int sql
32dd0 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
32de0 69 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72  ion(void (*xEntr
32df0 79 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a  yPoint)(void));.
32e00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32e10 20 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63   Reset Automatic
32e20 20 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69   Extension Loadi
32e30 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  ng.**.** ^This i
32e40 6e 74 65 72 66 61 63 65 20 64 69 73 61 62 6c 65  nterface disable
32e50 73 20 61 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20  s all automatic 
32e60 65 78 74 65 6e 73 69 6f 6e 73 20 70 72 65 76 69  extensions previ
32e70 6f 75 73 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  ously.** registe
32e80 72 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  red using [sqlit
32e90 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
32ea0 6e 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71  n()]..*/.void sq
32eb0 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
32ec0 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29  _extension(void)
32ed0 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  ;../*.** The int
32ee0 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
32ef0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
32f00 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74  anism is current
32f10 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
32f20 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
32f30 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
32f40 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
32f50 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
32f60 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
32f70 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
32f80 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
32f90 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
32fa0 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
32fb0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
32fc0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
32fd0 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73  anism stabilizes
32fe0 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
32ff0 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
33000 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
33010 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
33020 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
33030 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
33040 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73  /*.** Structures
33050 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72   used by the vir
33060 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
33070 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20  face.*/.typedef 
33080 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
33090 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62  tab sqlite3_vtab
330a0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
330b0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
330c0 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  nfo sqlite3_inde
330d0 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20  x_info;.typedef 
330e0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
330f0 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74  tab_cursor sqlit
33100 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a  e3_vtab_cursor;.
33110 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
33120 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71  qlite3_module sq
33130 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f  lite3_module;../
33140 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
33150 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a  irtual Table Obj
33160 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
33170 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
33180 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  {virtual table m
33190 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  odule}.**.** Thi
331a0 73 20 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d  s structure, som
331b0 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20  etimes called a 
331c0 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a "virtual table
331d0 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65   module", .** de
331e0 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d  fines the implem
331f0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76  entation of a [v
33200 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20  irtual tables]. 
33210 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74   .** This struct
33220 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73  ure consists mos
33230 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66  tly of methods f
33240 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a  or the module..*
33250 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c 20  *.** ^A virtual 
33260 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20  table module is 
33270 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69  created by filli
33280 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 65  ng in a persiste
33290 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  nt.** instance o
332a0 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
332b0 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70   and passing a p
332c0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69  ointer to that i
332d0 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73  nstance.** to [s
332e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
332f0 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  dule()] or [sqli
33300 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
33310 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  e_v2()]..** ^The
33320 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65   registration re
33330 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69  mains valid unti
33340 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64  l it is replaced
33350 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a   by a different.
33360 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74  ** module or unt
33370 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  il the [database
33380 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f   connection] clo
33390 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  ses.  The conten
333a0 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72  t.** of this str
333b0 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20  ucture must not 
333c0 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20  change while it 
333d0 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69  is registered wi
333e0 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61  th.** any databa
333f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  se connection..*
33400 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
33410 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20  _module {.  int 
33420 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
33430 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74  (*xCreate)(sqlit
33440 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
33450 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
33460 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
33470 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
33480 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
33490 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
334a0 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
334b0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63  .  int (*xConnec
334c0 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  t)(sqlite3*, voi
334d0 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
334e0 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
334f0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
33500 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
33510 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
33520 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
33530 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
33540 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c  *xBestIndex)(sql
33550 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
33560 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  , sqlite3_index_
33570 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  info*);.  int (*
33580 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c  xDisconnect)(sql
33590 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
335a0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74  );.  int (*xDest
335b0 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61  roy)(sqlite3_vta
335c0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
335d0 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
335e0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
335f0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
33600 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a  or **ppCursor);.
33610 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
33620 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
33630 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
33640 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f  Filter)(sqlite3_
33650 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e  vtab_cursor*, in
33660 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20  t idxNum, const 
33670 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20  char *idxStr,.  
33680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
33690 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f  t argc, sqlite3_
336a0 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20  value **argv);. 
336b0 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71   int (*xNext)(sq
336c0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
336d0 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f  r*);.  int (*xEo
336e0 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  f)(sqlite3_vtab_
336f0 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
33700 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74  (*xColumn)(sqlit
33710 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
33720 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
33730 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
33740 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33  *xRowid)(sqlite3
33750 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
33760 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52  qlite3_int64 *pR
33770 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  owid);.  int (*x
33780 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f  Update)(sqlite3_
33790 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c  vtab *, int, sql
337a0 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73  ite3_value **, s
337b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b  qlite3_int64 *);
337c0 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29  .  int (*xBegin)
337d0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
337e0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
337f0 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74  Sync)(sqlite3_vt
33800 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
33810 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c  t (*xCommit)(sql
33820 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
33830 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c  );.  int (*xRoll
33840 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74  back)(sqlite3_vt
33850 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
33860 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f  t (*xFindFunctio
33870 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
33880 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67  *pVtab, int nArg
33890 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
338a0 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20  ame,.           
338b0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
338c0 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69   (**pxFunc)(sqli
338d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
338e0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
338f0 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
33900 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a            void *
33910 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28  *ppArg);.  int (
33920 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65  *xRename)(sqlite
33930 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63  3_vtab *pVtab, c
33940 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29  onst char *zNew)
33950 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ;.};../*.** CAPI
33960 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
33970 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66  ble Indexing Inf
33980 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57  ormation.** KEYW
33990 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e  ORDS: sqlite3_in
339a0 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54  dex_info.**.** T
339b0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  he sqlite3_index
339c0 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20  _info structure 
339d0 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63  and its substruc
339e0 74 75 72 65 73 20 69 73 20 75 73 65 64 20 61 73  tures is used as
339f0 20 70 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20   part.** of the 
33a00 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
33a10 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
33a20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  pass information
33a30 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76   into and receiv
33a40 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d  e the reply from
33a50 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78   the [xBestIndex
33a60 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61  ].** method of a
33a70 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
33a80 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69  module].  The fi
33a90 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70  elds under **Inp
33aa0 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a  uts** are the.**
33ab0 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74   inputs to xBest
33ac0 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65  Index and are re
33ad0 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49  ad-only.  xBestI
33ae0 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73  ndex inserts its
33af0 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
33b00 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a   the **Outputs**
33b10 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e   fields..**.** ^
33b20 28 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74  (The aConstraint
33b30 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73  [] array records
33b40 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
33b50 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65  nstraints of the
33b60 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   form:.**.** <bl
33b70 6f 63 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d 6e 20  ockquote>column 
33b80 4f 50 20 65 78 70 72 3c 2f 62 6c 6f 63 6b 71 75  OP expr</blockqu
33b90 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65  ote>.**.** where
33ba0 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20   OP is =, &lt;, 
33bb0 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20  &lt;=, &gt;, or 
33bc0 26 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20  &gt;=.)^  ^(The 
33bd0 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61  particular opera
33be0 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64  tor is.** stored
33bf0 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b   in aConstraint[
33c00 5d 2e 6f 70 20 75 73 69 6e 67 20 6f 6e 65 20 6f  ].op using one o
33c10 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
33c20 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
33c30 54 5f 45 51 20 7c 20 53 51 4c 49 54 45 5f 49 4e  T_EQ | SQLITE_IN
33c40 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 20  DEX_CONSTRAINT_ 
33c50 76 61 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20 5e 28  values].)^.** ^(
33c60 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  The index of the
33c70 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65   column is store
33c80 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61  d in.** aConstra
33c90 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e  int[].iColumn.)^
33ca0 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b    ^(aConstraint[
33cb0 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45  ].usable is TRUE
33cc0 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20   if the.** expr 
33cd0 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  on the right-han
33ce0 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76  d side can be ev
33cf0 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75  aluated (and thu
33d00 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  s the constraint
33d10 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61  .** is usable) a
33d20 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63  nd false if it c
33d30 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  annot.)^.**.** ^
33d40 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75  The optimizer au
33d50 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65  tomatically inve
33d60 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65  rts terms of the
33d70 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63   form "expr OP c
33d80 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61  olumn".** and ma
33d90 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69  kes other simpli
33da0 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65  fications to the
33db0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e   WHERE clause in
33dc0 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a   an attempt to.*
33dd0 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48  * get as many WH
33de0 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73  ERE clause terms
33df0 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73   into the form s
33e00 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f  hown above as po
33e10 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20  ssible..** ^The 
33e20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
33e30 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
33e40 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
33e50 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  rms that are.** 
33e60 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68 65 20  relevant to the 
33e70 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75  particular virtu
33e80 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71  al table being q
33e90 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ueried..**.** ^I
33ea0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
33eb0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
33ec0 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69  ause is stored i
33ed0 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a  n aOrderBy[]..**
33ee0 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61   ^Each term of a
33ef0 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20  OrderBy records 
33f00 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  a column of the 
33f10 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e  ORDER BY clause.
33f20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73  .**.** The [xBes
33f30 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d  tIndex] method m
33f40 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72  ust fill aConstr
33f50 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68  aintUsage[] with
33f60 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
33f70 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d  about what param
33f80 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f  eters to pass to
33f90 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66 20 61   xFilter.  ^If a
33fa0 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a  rgvIndex>0 then.
33fb0 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  ** the right-han
33fc0 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f  d side of the co
33fd0 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e  rresponding aCon
33fe0 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61  straint[] is eva
33ff0 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65  luated.** and be
34000 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e  comes the argvIn
34010 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20  dex-th entry in 
34020 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e  argv.  ^(If aCon
34030 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f  straintUsage[].o
34040 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20  mit.** is true, 
34050 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61  then the constra
34060 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74  int is assumed t
34070 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c  o be fully handl
34080 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72  ed by the.** vir
34090 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69  tual table and i
340a0 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67  s not checked ag
340b0 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 29 5e  ain by SQLite.)^
340c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 78 4e  .**.** ^The idxN
340d0 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61  um and idxPtr va
340e0 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65  lues are recorde
340f0 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74  d and passed int
34100 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65  o the.** [xFilte
34110 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b  r] method..** ^[
34120 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
34130 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20  is used to free 
34140 69 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e  idxPtr if and on
34150 6c 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54 6f 46  ly if.** needToF
34160 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75  reeIdxPtr is tru
34170 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72  e..**.** ^The or
34180 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65  derByConsumed me
34190 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20  ans that output 
341a0 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b  from [xFilter]/[
341b0 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75  xNext] will occu
341c0 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72  r in.** the corr
341d0 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74  ect order to sat
341e0 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42  isfy the ORDER B
341f0 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74  Y clause so that
34200 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20   no separate.** 
34210 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20  sorting step is 
34220 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
34230 5e 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f  ^The estimatedCo
34240 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65  st value is an e
34250 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63  stimate of the c
34260 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65  ost of doing the
34270 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c  .** particular l
34280 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73  ookup.  A full s
34290 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77  can of a table w
342a0 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68  ith N entries sh
342b0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63  ould have.** a c
342c0 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e  ost of N.  A bin
342d0 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20  ary search of a 
342e0 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69  table of N entri
342f0 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61  es should have a
34300 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72  .** cost of appr
34310 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29  oximately log(N)
34320 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
34330 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b  te3_index_info {
34340 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a  .  /* Inputs */.
34350 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e    int nConstrain
34360 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t;           /* 
34370 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65  Number of entrie
34380 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  s in aConstraint
34390 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
343a0 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
343b0 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74  raint {.     int
343c0 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
343d0 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
343e0 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69   on left-hand si
343f0 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74  de of constraint
34400 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
34410 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20  d char op;      
34420 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74     /* Constraint
34430 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20   operator */.   
34440 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
34450 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54  usable;     /* T
34460 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73  rue if this cons
34470 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65  traint is usable
34480 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65   */.     int iTe
34490 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20  rmOffset;       
344a0 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72     /* Used inter
344b0 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64  nally - xBestInd
344c0 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65  ex should ignore
344d0 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72   */.  } *aConstr
344e0 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20  aint;           
344f0 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45   /* Table of WHE
34500 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
34510 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  aints */.  int n
34520 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20  OrderBy;        
34530 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
34540 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20  of terms in the 
34550 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
34560 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
34570 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62  te3_index_orderb
34580 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  y {.     int iCo
34590 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
345a0 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d     /* Column num
345b0 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  ber */.     unsi
345c0 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20  gned char desc; 
345d0 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f        /* True fo
345e0 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66  r DESC.  False f
345f0 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a  or ASC. */.  } *
34600 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  aOrderBy;       
34610 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f          /* The O
34620 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
34630 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a  /.  /* Outputs *
34640 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
34650 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
34660 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20  int_usage {.    
34670 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20  int argvIndex;  
34680 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e           /* if >
34690 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  0, constraint is
346a0 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f   part of argv to
346b0 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20   xFilter */.    
346c0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d  unsigned char om
346d0 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e  it;      /* Do n
346e0 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66  ot code a test f
346f0 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  or this constrai
34700 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73  nt */.  } *aCons
34710 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69  traintUsage;.  i
34720 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20  nt idxNum;      
34730 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
34740 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e  ber used to iden
34750 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a  tify the index *
34760 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72  /.  char *idxStr
34770 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
34780 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62  * String, possib
34790 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
347a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20   sqlite3_malloc 
347b0 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46  */.  int needToF
347c0 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20  reeIdxStr;      
347d0 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75  /* Free idxStr u
347e0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  sing sqlite3_fre
347f0 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20  e() if true */. 
34800 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73   int orderByCons
34810 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54  umed;       /* T
34820 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73  rue if output is
34830 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64   already ordered
34840 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74   */.  double est
34850 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20  imatedCost;     
34860 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f   /* Estimated co
34870 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  st of using this
34880 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f 2a   index */.};../*
34890 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
348a0 72 74 75 61 6c 20 54 61 62 6c 65 20 43 6f 6e 73  rtual Table Cons
348b0 74 72 61 69 6e 74 20 4f 70 65 72 61 74 6f 72 20  traint Operator 
348c0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Codes.**.** Thes
348d0 65 20 6d 61 63 72 6f 73 20 64 65 66 69 6e 65 64  e macros defined
348e0 20 74 68 65 20 61 6c 6c 6f 77 65 64 20 76 61 6c   the allowed val
348f0 75 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  ues for the.** [
34900 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
34910 66 6f 5d 2e 61 43 6f 6e 73 74 72 61 69 6e 74 5b  fo].aConstraint[
34920 5d 2e 6f 70 20 66 69 65 6c 64 2e 20 20 45 61 63  ].op field.  Eac
34930 68 20 76 61 6c 75 65 20 72 65 70 72 65 73 65 6e  h value represen
34940 74 73 0a 2a 2a 20 61 6e 20 6f 70 65 72 61 74 6f  ts.** an operato
34950 72 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f  r that is part o
34960 66 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 74  f a constraint t
34970 65 72 6d 20 69 6e 20 74 68 65 20 77 48 45 52 45  erm in the wHERE
34980 20 63 6c 61 75 73 65 20 6f 66 0a 2a 2a 20 61 20   clause of.** a 
34990 71 75 65 72 79 20 74 68 61 74 20 75 73 65 73 20  query that uses 
349a0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
349b0 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
349c0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
349d0 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64  RAINT_EQ    2.#d
349e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
349f0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54  EX_CONSTRAINT_GT
34a00 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
34a10 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
34a20 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64  RAINT_LE    8.#d
34a30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
34a40 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54  EX_CONSTRAINT_LT
34a50 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
34a60 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
34a70 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a  TRAINT_GE    32.
34a80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
34a90 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
34aa0 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20  MATCH 64../*.** 
34ab0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
34ac0 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  er A Virtual Tab
34ad0 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le Implementatio
34ae0 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
34af0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
34b00 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e   to register a n
34b10 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ew [virtual tabl
34b20 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a  e module] name..
34b30 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73  ** ^Module names
34b40 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65   must be registe
34b50 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72  red before.** cr
34b60 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69  eating a new [vi
34b70 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69  rtual table] usi
34b80 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e  ng the module an
34b90 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61  d before using a
34ba0 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20  .** preexisting 
34bb0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
34bc0 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
34bd0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c  **.** ^The modul
34be0 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74  e name is regist
34bf0 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74  ered on the [dat
34c00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34c10 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  ] specified.** b
34c20 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
34c30 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d  meter.  ^The nam
34c40 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
34c50 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  is given by the 
34c60 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
34c70 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72  eter.  ^The thir
34c80 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
34c90 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74   pointer to.** t
34ca0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
34cb0 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  n of the [virtua
34cc0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
34cd0 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a     ^The fourth.*
34ce0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  * parameter is a
34cf0 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65  n arbitrary clie
34d00 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  nt data pointer 
34d10 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74  that is passed t
34d20 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74  hrough.** into t
34d30 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64  he [xCreate] and
34d40 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68   [xConnect] meth
34d50 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75  ods of the virtu
34d60 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a  al table module.
34d70 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69  ** when a new vi
34d80 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62  rtual table is b
34d90 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20  e being created 
34da0 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64  or reinitialized
34db0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34dc0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
34dd0 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  le_v2() interfac
34de0 65 20 68 61 73 20 61 20 66 69 66 74 68 20 70 61  e has a fifth pa
34df0 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
34e00 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
34e10 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
34e20 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74  r the pClientDat
34e30 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  a.  ^SQLite will
34e40 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  .** invoke the d
34e50 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
34e60 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74  on (if it is not
34e70 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69   NULL) when SQLi
34e80 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20  te.** no longer 
34e90 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e  needs the pClien
34ea0 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20  tData pointer.  
34eb0 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
34ec0 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
34ed0 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
34ee0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
34ef0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
34f00 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 54 68 65  ) fails..** ^The
34f10 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34f20 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65  module().** inte
34f30 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c  rface is equival
34f40 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
34f50 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
34f60 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a  ) with a NULL.**
34f70 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a   destructor..*/.
34f80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
34f90 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c  te_module(.  sql
34fa0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
34fb0 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74          /* SQLit
34fc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
34fd0 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20  register module 
34fe0 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  with */.  const 
34ff0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20  char *zName,    
35000 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
35010 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20  the module */.  
35020 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f  const sqlite3_mo
35030 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65  dule *p,   /* Me
35040 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
35050 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  dule */.  void *
35060 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20  pClientData     
35070 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64       /* Client d
35080 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f  ata for xCreate/
35090 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69  xConnect */.);.i
350a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
350b0 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73  e_module_v2(.  s
350c0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
350d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
350e0 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
350f0 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
35100 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
35110 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
35120 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
35130 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
35140 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
35150 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
35160 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
35170 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
35180 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20   *pClientData,  
35190 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
351a0 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
351b0 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20  e/xConnect */.  
351c0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
351d0 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f  void*)     /* Mo
351e0 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20  dule destructor 
351f0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a  function */.);..
35200 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35210 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e  Virtual Table In
35220 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  stance Object.**
35230 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
35240 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76  e3_vtab.**.** Ev
35250 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62  ery [virtual tab
35260 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65  le module] imple
35270 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61  mentation uses a
35280 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20   subclass.** of 
35290 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20 64  this object to d
352a0 65 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63  escribe a partic
352b0 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a  ular instance.**
352c0 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
352d0 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73   table].  Each s
352e0 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20  ubclass will.** 
352f0 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74  be tailored to t
35300 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
35310 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  s of the module 
35320 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a  implementation..
35330 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f  ** The purpose o
35340 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73  f this superclas
35350 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63  s is to define c
35360 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68  ertain fields th
35370 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e  at are.** common
35380 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69   to all module i
35390 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a  mplementations..
353a0 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74  **.** ^Virtual t
353b0 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61  ables methods ca
353c0 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d  n set an error m
353d0 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e  essage by assign
353e0 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20  ing a.** string 
353f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
35400 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
35410 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54  ] to zErrMsg.  T
35420 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  he method should
35430 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68  .** take care th
35440 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72  at any prior str
35450 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20  ing is freed by 
35460 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
35470 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72  e3_free()].** pr
35480 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67  ior to assigning
35490 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f   a new string to
354a0 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74 65   zErrMsg.  ^Afte
354b0 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
354c0 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65  age.** is delive
354d0 72 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c  red up to the cl
354e0 69 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  ient application
354f0 2c 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  , the string wil
35500 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
35510 6c 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73  ly.** freed by s
35520 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e  qlite3_free() an
35530 64 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69  d the zErrMsg fi
35540 65 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f  eld will be zero
35550 65 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ed..*/.struct sq
35560 6c 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63  lite3_vtab {.  c
35570 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
35580 75 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f  ule *pModule;  /
35590 2a 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72  * The module for
355a0 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61   this virtual ta
355b0 62 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65  ble */.  int nRe
355c0 66 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  f;              
355d0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c           /* NO L
355e0 4f 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20 20  ONGER USED */.  
355f0 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20  char *zErrMsg;  
35600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35610 2f 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65  /* Error message
35620 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70   from sqlite3_mp
35630 72 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20  rintf() */.  /* 
35640 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d  Virtual table im
35650 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
35660 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64  ll typically add
35670 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c   additional fiel
35680 64 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  ds */.};../*.** 
35690 43 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61  CAPI3REF: Virtua
356a0 6c 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f  l Table Cursor O
356b0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
356c0 53 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  S: sqlite3_vtab_
356d0 63 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20  cursor {virtual 
356e0 74 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a  table cursor}.**
356f0 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75  .** Every [virtu
35700 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
35710 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35720 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20  uses a subclass 
35730 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  of the.** follow
35740 69 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f  ing structure to
35750 20 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72   describe cursor
35760 73 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74  s that point int
35770 6f 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61  o the.** [virtua
35780 6c 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65  l table] and are
35790 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70   used.** to loop
357a0 20 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72   through the vir
357b0 74 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72  tual table.  Cur
357c0 73 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64  sors are created
357d0 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
357e0 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f  qlite3_module.xO
357f0 70 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74  pen | xOpen] met
35800 68 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c  hod of the modul
35810 65 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f  e and are destro
35820 79 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73  yed.** by the [s
35830 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43  qlite3_module.xC
35840 6c 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d  lose | xClose] m
35850 65 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 73 20  ethod.  Cursors 
35860 61 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74  are used.** by t
35870 68 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78  he [xFilter], [x
35880 4e 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b  Next], [xEof], [
35890 78 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78  xColumn], and [x
358a0 52 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a  Rowid] methods.*
358b0 2a 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e  * of the module.
358c0 20 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d    Each module im
358d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
358e0 6c 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  l define.** the 
358f0 63 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72  content of a cur
35900 73 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f  sor structure to
35910 20 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65   suit its own ne
35920 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  eds..**.** This 
35930 73 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74  superclass exist
35940 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65  s in order to de
35950 66 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74  fine fields of t
35960 68 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a  he cursor that.*
35970 2a 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20  * are common to 
35980 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  all implementati
35990 6f 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73  ons..*/.struct s
359a0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
359b0 6f 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76  or {.  sqlite3_v
359c0 74 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20  tab *pVtab;     
359d0 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c   /* Virtual tabl
359e0 65 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72  e of this cursor
359f0 20 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c   */.  /* Virtual
35a00 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
35a10 61 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69  ations will typi
35a20 63 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69  cally add additi
35a30 6f 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d  onal fields */.}
35a40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35a50 46 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53  F: Declare The S
35a60 63 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75  chema Of A Virtu
35a70 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e  al Table.**.** ^
35a80 54 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  The [xCreate] an
35a90 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
35aa0 68 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69  hods of a.** [vi
35ab0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
35ac0 6c 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e  le] call this in
35ad0 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65  terface.** to de
35ae0 63 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74  clare the format
35af0 20 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20   (the names and 
35b00 64 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65  datatypes of the
35b10 20 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20   columns) of.** 
35b20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c  the virtual tabl
35b30 65 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e  es they implemen
35b40 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
35b50 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73  3_declare_vtab(s
35b60 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
35b70 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a  har *zSQL);../*.
35b80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65  ** CAPI3REF: Ove
35b90 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e  rload A Function
35ba0 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54   For A Virtual T
35bb0 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72  able.**.** ^(Vir
35bc0 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20  tual tables can 
35bd0 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74  provide alternat
35be0 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ive implementati
35bf0 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73  ons of functions
35c00 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78  .** using the [x
35c10 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65  FindFunction] me
35c20 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72  thod of the [vir
35c30 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
35c40 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f  e].  .** But glo
35c50 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  bal versions of 
35c60 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a  those functions.
35c70 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e  ** must exist in
35c80 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65   order to be ove
35c90 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  rloaded.)^.**.**
35ca0 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b 65   ^(This API make
35cb0 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20  s sure a global 
35cc0 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e  version of a fun
35cd0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72  ction with a par
35ce0 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20  ticular.** name 
35cf0 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  and number of pa
35d00 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e  rameters exists.
35d10 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e    If no such fun
35d20 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20  ction exists.** 
35d30 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20  before this API 
35d40 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77  is called, a new
35d50 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65   function is cre
35d60 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d  ated.)^  ^The im
35d70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
35d80 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  of the new funct
35d90 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65  ion always cause
35da0 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74  s an exception t
35db0 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f  o be thrown.  So
35dc0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63  .** the new func
35dd0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64  tion is not good
35de0 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79   for anything by
35df0 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e   itself.  Its on
35e00 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73  ly.** purpose is
35e10 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f   to be a placeho
35e20 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68  lder function th
35e30 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f  at can be overlo
35e40 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69  aded.** by a [vi
35e50 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f  rtual table]..*/
35e60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65  .int sqlite3_ove
35e70 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73  rload_function(s
35e80 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63  qlite3*, const c
35e90 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20  har *zFuncName, 
35ea0 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a  int nArg);../*.*
35eb0 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
35ec0 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
35ed0 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64  able mechanism d
35ee0 65 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61  efined above (ba
35ef0 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f  ck up.** to a co
35f00 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79  mment remarkably
35f10 20 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73   similar to this
35f20 20 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74   one) is current
35f30 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
35f40 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
35f50 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
35f60 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
35f70 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
35f80 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
35f90 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
35fa0 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
35fb0 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
35fc0 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
35fd0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
35fe0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
35ff0 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73  anism stabilizes
36000 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
36010 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
36020 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
36030 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
36040 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
36050 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
36060 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36070 41 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f  A Handle To An O
36080 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57  pen BLOB.** KEYW
36090 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64  ORDS: {BLOB hand
360a0 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65  le} {BLOB handle
360b0 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
360c0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
360d0 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
360e0 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77  n open BLOB on w
360f0 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
36100 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
36110 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
36120 4f 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  O] can be perfor
36130 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73  med..** ^Objects
36140 20 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72   of this type ar
36150 65 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71  e created by [sq
36160 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
36170 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f  )].** and destro
36180 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
36190 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  blob_close()]..*
361a0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
361b0 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64  blob_read()] and
361c0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77   [sqlite3_blob_w
361d0 72 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63  rite()] interfac
361e0 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  es.** can be use
361f0 64 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69  d to read or wri
36200 74 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74  te small subsect
36210 69 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ions of the BLOB
36220 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
36230 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
36240 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
36250 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  ns the size of t
36260 68 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73  he BLOB in bytes
36270 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
36280 75 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  uct sqlite3_blob
36290 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a   sqlite3_blob;..
362a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
362b0 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20  Open A BLOB For 
362c0 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a  Incremental I/O.
362d0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
362e0 65 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20  erfaces opens a 
362f0 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68  [BLOB handle | h
36300 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c  andle] to the BL
36310 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e  OB located.** in
36320 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d   row iRow, colum
36330 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65  n zColumn, table
36340 20 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62   zTable in datab
36350 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f  ase zDb;.** in o
36360 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
36370 73 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77  same BLOB that w
36380 6f 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64  ould be selected
36390 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e   by:.**.** <pre>
363a0 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a  .**     SELECT z
363b0 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e  Column FROM zDb.
363c0 7a 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f  zTable WHERE [ro
363d0 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20  wid] = iRow;.** 
363e0 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  </pre>)^.**.** ^
363f0 49 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  If the flags par
36400 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65  ameter is non-ze
36410 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f  ro, then the BLO
36420 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  B is opened for 
36430 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74  read.** and writ
36440 65 20 61 63 63 65 73 73 2e 20 5e 49 66 20 69 74  e access. ^If it
36450 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c   is zero, the BL
36460 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  OB is opened for
36470 20 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a   read access..**
36480 20 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73   ^It is not poss
36490 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63  ible to open a c
364a0 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61  olumn that is pa
364b0 72 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f  rt of an index o
364c0 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65  r primary .** ke
364d0 79 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e  y for writing. ^
364e0 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  If [foreign key 
364f0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65  constraints] are
36500 20 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20   enabled, it is 
36510 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  .** not possible
36520 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d   to open a colum
36530 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f  n that is part o
36540 66 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20  f a [child key] 
36550 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a  for writing..**.
36560 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
36570 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20  e database name 
36580 69 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e  is not the filen
36590 61 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ame that contain
365a0 73 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  s.** the databas
365b0 65 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65  e but rather the
365c0 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f   symbolic name o
365d0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  f the database t
365e0 68 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 20 61  hat.** appears a
365f0 66 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77  fter the AS keyw
36600 6f 72 64 20 77 68 65 6e 20 74 68 65 20 64 61 74  ord when the dat
36610 61 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74  abase is connect
36620 65 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48  ed using [ATTACH
36630 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d  ]..** ^For the m
36640 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
36650 65 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20  e, the database 
36660 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a  name is "main"..
36670 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 61 62  ** ^For TEMP tab
36680 6c 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73  les, the databas
36690 65 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22  e name is "temp"
366a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63  ..**.** ^(On suc
366b0 63 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  cess, [SQLITE_OK
366c0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e  ] is returned an
366d0 64 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20  d the new [BLOB 
366e0 68 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74  handle] is writt
366f0 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62  en.** to *ppBlob
36700 2e 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  . Otherwise an [
36710 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
36720 65 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42  eturned and *ppB
36730 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  lob is set.** to
36740 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74   be a null point
36750 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66  er.)^.** ^This f
36760 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65  unction sets the
36770 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36780 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64  ction] error cod
36790 65 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a  e and message.**
367a0 20 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20   accessible via 
367b0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
367c0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
367d0 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72  _errmsg()] and r
367e0 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69  elated.** functi
367f0 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20  ons. ^Note that 
36800 74 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69  the *ppBlob vari
36810 61 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69  able is always i
36820 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a  nitialized in a.
36830 2a 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65  ** way that make
36840 73 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76  s it safe to inv
36850 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  oke [sqlite3_blo
36860 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70  b_close()] on *p
36870 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c  pBlob.** regardl
36880 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
36890 73 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ss or failure of
368a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a   this routine..*
368b0 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 72 6f  *.** ^(If the ro
368c0 77 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61  w that a BLOB ha
368d0 6e 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69  ndle points to i
368e0 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e  s modified by an
368f0 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44  .** [UPDATE], [D
36900 45 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f  ELETE], or by [O
36910 4e 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65  N CONFLICT] side
36920 2d 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e  -effects.** then
36930 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
36940 20 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65   is marked as "e
36950 78 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73  xpired"..** This
36960 20 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20   is true if any 
36970 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f  column of the ro
36980 77 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76  w is changed, ev
36990 65 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f  en a column.** o
369a0 74 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e  ther than the on
369b0 65 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c  e the BLOB handl
369c0 65 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a  e is open on.)^.
369d0 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71  ** ^Calls to [sq
369e0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28  lite3_blob_read(
369f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
36a00 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f  blob_write()] fo
36a10 72 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42  r.** a expired B
36a20 4c 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20  LOB handle fail 
36a30 77 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63  with an return c
36a40 6f 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41  ode of [SQLITE_A
36a50 42 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e  BORT]..** ^(Chan
36a60 67 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  ges written into
36a70 20 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f   a BLOB prior to
36a80 20 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69   the BLOB expiri
36a90 6e 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f  ng are not.** ro
36aa0 6c 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65  lled back by the
36ab0 20 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74   expiration of t
36ac0 68 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63  he BLOB.  Such c
36ad0 68 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e  hanges will even
36ae0 74 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74  tually.** commit
36af0 20 69 66 20 74 68 65 20 74 72 61 6e 73 61 63 74   if the transact
36b00 69 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ion continues to
36b10 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a   completion.)^.*
36b20 2a 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b 73  *.** ^Use the [s
36b30 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65  qlite3_blob_byte
36b40 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  s()] interface t
36b50 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
36b60 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  size of.** the o
36b70 70 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54 68  pened blob.  ^Th
36b80 65 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62  e size of a blob
36b90 20 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e   may not be chan
36ba0 67 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 69  ged by this.** i
36bb0 6e 74 65 72 66 61 63 65 2e 20 20 55 73 65 20 74  nterface.  Use t
36bc0 68 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20  he [UPDATE] SQL 
36bd0 63 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67  command to chang
36be0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a  e the size of a.
36bf0 2a 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e  ** blob..**.** ^
36c00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  The [sqlite3_bin
36c10 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e  d_zeroblob()] an
36c20 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
36c30 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e  t_zeroblob()] in
36c40 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20  terfaces.** and 
36c50 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65  the built-in [ze
36c60 72 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63  roblob] SQL func
36c70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
36c80 2c 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a  , if desired,.**
36c90 20 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d   to create an em
36ca0 70 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64  pty, zero-filled
36cb0 20 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74   blob in which t
36cc0 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  o read or write 
36cd0 75 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e  using.** this in
36ce0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
36cf0 6f 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72  o avoid a resour
36d00 63 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f  ce leak, every o
36d10 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  pen [BLOB handle
36d20 5d 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61  ] should eventua
36d30 6c 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73  lly.** be releas
36d40 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
36d50 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
36d60 6f 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ose()]..*/.int s
36d70 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
36d80 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
36d90 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c  const char *zDb,
36da0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
36db0 54 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63  Table,.  const c
36dc0 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20  har *zColumn,.  
36dd0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52  sqlite3_int64 iR
36de0 6f 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c  ow,.  int flags,
36df0 0a 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  .  sqlite3_blob 
36e00 2a 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a  **ppBlob.);../*.
36e10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 6f 76  ** CAPI3REF: Mov
36e20 65 20 61 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20  e a BLOB Handle 
36e30 74 6f 20 61 20 4e 65 77 20 52 6f 77 0a 2a 2a 0a  to a New Row.**.
36e40 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
36e50 20 69 73 20 75 73 65 64 20 74 6f 20 6d 6f 76 65   is used to move
36e60 20 61 6e 20 65 78 69 73 74 69 6e 67 20 62 6c 6f   an existing blo
36e70 62 20 68 61 6e 64 6c 65 20 73 6f 20 74 68 61 74  b handle so that
36e80 20 69 74 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f   it points.** to
36e90 20 61 20 64 69 66 66 65 72 65 6e 74 20 72 6f 77   a different row
36ea0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 64 61 74   of the same dat
36eb0 61 62 61 73 65 20 74 61 62 6c 65 2e 20 54 68 65  abase table. The
36ec0 20 6e 65 77 20 72 6f 77 20 69 73 20 69 64 65 6e   new row is iden
36ed0 74 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  tified.** by the
36ee0 20 72 6f 77 69 64 20 76 61 6c 75 65 20 70 61 73   rowid value pas
36ef0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
36f00 64 20 61 72 67 75 6d 65 6e 74 2e 20 4f 6e 6c 79  d argument. Only
36f10 20 74 68 65 20 72 6f 77 20 63 61 6e 20 62 65 0a   the row can be.
36f20 2a 2a 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  ** changed, the 
36f30 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 20  database, table 
36f40 61 6e 64 20 63 6f 6c 75 6d 6e 20 6f 6e 20 77 68  and column on wh
36f50 69 63 68 20 74 68 65 20 62 6c 6f 62 20 68 61 6e  ich the blob han
36f60 64 6c 65 20 69 73 20 6f 70 65 6e 0a 2a 2a 20 72  dle is open.** r
36f70 65 6d 61 69 6e 20 74 68 65 20 73 61 6d 65 2e 20  emain the same. 
36f80 4d 6f 76 69 6e 67 20 61 6e 20 65 78 69 73 74 69  Moving an existi
36f90 6e 67 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 74  ng blob handle t
36fa0 6f 20 61 20 6e 65 77 20 72 6f 77 20 63 61 6e 20  o a new row can 
36fb0 62 65 0a 2a 2a 20 66 61 73 74 65 72 20 74 68 61  be.** faster tha
36fc0 6e 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 65 78  n closing the ex
36fd0 69 73 74 69 6e 67 20 68 61 6e 64 6c 65 20 61 6e  isting handle an
36fe0 64 20 6f 70 65 6e 69 6e 67 20 61 20 6e 65 77 20  d opening a new 
36ff0 6f 6e 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e  one..**.** The n
37000 65 77 20 72 6f 77 20 6d 75 73 74 20 6d 65 65 74  ew row must meet
37010 20 74 68 65 20 73 61 6d 65 20 63 72 69 74 65 72   the same criter
37020 69 61 20 61 73 20 66 6f 72 20 5b 73 71 6c 69 74  ia as for [sqlit
37030 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20  e3_blob_open()] 
37040 2d 0a 2a 2a 20 69 74 20 6d 75 73 74 20 65 78 69  -.** it must exi
37050 73 74 20 61 6e 64 20 74 68 65 72 65 20 6d 75 73  st and there mus
37060 74 20 62 65 20 65 69 74 68 65 72 20 61 20 62 6c  t be either a bl
37070 6f 62 20 6f 72 20 74 65 78 74 20 76 61 6c 75 65  ob or text value
37080 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 74 68   stored in.** th
37090 65 20 6e 6f 6d 69 6e 61 74 65 64 20 63 6f 6c 75  e nominated colu
370a0 6d 6e 2e 20 49 66 20 74 68 65 20 6e 65 77 20 72  mn. If the new r
370b0 6f 77 20 69 73 20 6e 6f 74 20 70 72 65 73 65 6e  ow is not presen
370c0 74 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2c 20  t in the table, 
370d0 6f 72 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  or if.** it does
370e0 20 6e 6f 74 20 63 6f 6e 74 61 69 6e 20 61 20 62   not contain a b
370f0 6c 6f 62 20 6f 72 20 74 65 78 74 20 76 61 6c 75  lob or text valu
37100 65 2c 20 6f 72 20 69 66 20 61 6e 6f 74 68 65 72  e, or if another
37110 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 61   error occurs, a
37120 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 72 72 6f  n.** SQLite erro
37130 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
37140 65 64 20 61 6e 64 20 74 68 65 20 62 6c 6f 62 20  ed and the blob 
37150 68 61 6e 64 6c 65 20 69 73 20 63 6f 6e 73 69 64  handle is consid
37160 65 72 65 64 20 61 62 6f 72 74 65 64 2e 0a 2a 2a  ered aborted..**
37170 20 41 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   All subsequent 
37180 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
37190 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2c 20  3_blob_read()], 
371a0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
371b0 69 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ite()] or.** [sq
371c0 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 6f 70 65  lite3_blob_reope
371d0 6e 28 29 5d 20 6f 6e 20 61 6e 20 61 62 6f 72 74  n()] on an abort
371e0 65 64 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69  ed blob handle i
371f0 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72  mmediately retur
37200 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 42 4f 52  n.** SQLITE_ABOR
37210 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  T..**.** This fu
37220 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20  nction sets the 
37230 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  database handle 
37240 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d  error code and m
37250 65 73 73 61 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54  essage..*/.SQLIT
37260 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 69  E_EXPERIMENTAL i
37270 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
37280 72 65 6f 70 65 6e 28 73 71 6c 69 74 65 33 5f 62  reopen(sqlite3_b
37290 6c 6f 62 20 2a 2c 20 73 71 6c 69 74 65 33 5f 69  lob *, sqlite3_i
372a0 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
372b0 50 49 33 52 45 46 3a 20 43 6c 6f 73 65 20 41 20  PI3REF: Close A 
372c0 42 4c 4f 42 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  BLOB Handle.**.*
372d0 2a 20 5e 43 6c 6f 73 65 73 20 61 6e 20 6f 70 65  * ^Closes an ope
372e0 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 2e  n [BLOB handle].
372f0 0a 2a 2a 0a 2a 2a 20 5e 43 6c 6f 73 69 6e 67 20  .**.** ^Closing 
37300 61 20 42 4c 4f 42 20 73 68 61 6c 6c 20 63 61 75  a BLOB shall cau
37310 73 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  se the current t
37320 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 63 6f  ransaction to co
37330 6d 6d 69 74 0a 2a 2a 20 69 66 20 74 68 65 72 65  mmit.** if there
37340 20 61 72 65 20 6e 6f 20 6f 74 68 65 72 20 42 4c   are no other BL
37350 4f 42 73 2c 20 6e 6f 20 70 65 6e 64 69 6e 67 20  OBs, no pending 
37360 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37370 6e 74 73 2c 20 61 6e 64 20 74 68 65 0a 2a 2a 20  nts, and the.** 
37380 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37390 69 6f 6e 20 69 73 20 69 6e 20 5b 61 75 74 6f 63  ion is in [autoc
373a0 6f 6d 6d 69 74 20 6d 6f 64 65 5d 2e 0a 2a 2a 20  ommit mode]..** 
373b0 5e 49 66 20 61 6e 79 20 77 72 69 74 65 73 20 77  ^If any writes w
373c0 65 72 65 20 6d 61 64 65 20 74 6f 20 74 68 65 20  ere made to the 
373d0 42 4c 4f 42 2c 20 74 68 65 79 20 6d 69 67 68 74  BLOB, they might
373e0 20 62 65 20 68 65 6c 64 20 69 6e 20 63 61 63 68   be held in cach
373f0 65 0a 2a 2a 20 75 6e 74 69 6c 20 74 68 65 20 63  e.** until the c
37400 6c 6f 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 69  lose operation i
37410 66 20 74 68 65 79 20 77 69 6c 6c 20 66 69 74 2e  f they will fit.
37420 0a 2a 2a 0a 2a 2a 20 5e 28 43 6c 6f 73 69 6e 67  .**.** ^(Closing
37430 20 74 68 65 20 42 4c 4f 42 20 6f 66 74 65 6e 20   the BLOB often 
37440 66 6f 72 63 65 73 20 74 68 65 20 63 68 61 6e 67  forces the chang
37450 65 73 0a 2a 2a 20 6f 75 74 20 74 6f 20 64 69 73  es.** out to dis
37460 6b 20 61 6e 64 20 73 6f 20 69 66 20 61 6e 79 20  k and so if any 
37470 49 2f 4f 20 65 72 72 6f 72 73 20 6f 63 63 75 72  I/O errors occur
37480 2c 20 74 68 65 79 20 77 69 6c 6c 20 6c 69 6b 65  , they will like
37490 6c 79 20 6f 63 63 75 72 0a 2a 2a 20 61 74 20 74  ly occur.** at t
374a0 68 65 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  he time when the
374b0 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 2e   BLOB is closed.
374c0 20 20 41 6e 79 20 65 72 72 6f 72 73 20 74 68 61    Any errors tha
374d0 74 20 6f 63 63 75 72 20 64 75 72 69 6e 67 0a 2a  t occur during.*
374e0 2a 20 63 6c 6f 73 69 6e 67 20 61 72 65 20 72 65  * closing are re
374f0 70 6f 72 74 65 64 20 61 73 20 61 20 6e 6f 6e 2d  ported as a non-
37500 7a 65 72 6f 20 72 65 74 75 72 6e 20 76 61 6c 75  zero return valu
37510 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  e.)^.**.** ^(The
37520 20 42 4c 4f 42 20 69 73 20 63 6c 6f 73 65 64 20   BLOB is closed 
37530 75 6e 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 2e  unconditionally.
37540 20 20 45 76 65 6e 20 69 66 20 74 68 69 73 20 72    Even if this r
37550 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 0a 2a  outine returns.*
37560 2a 20 61 6e 20 65 72 72 6f 72 20 63 6f 64 65 2c  * an error code,
37570 20 74 68 65 20 42 4c 4f 42 20 69 73 20 73 74 69   the BLOB is sti
37580 6c 6c 20 63 6c 6f 73 65 64 2e 29 5e 0a 2a 2a 0a  ll closed.)^.**.
37590 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
375a0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
375b0 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 20 28 73 75  null pointer (su
375c0 63 68 20 61 73 20 77 6f 75 6c 64 20 62 65 20 72  ch as would be r
375d0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 61 20  eturned.** by a 
375e0 66 61 69 6c 65 64 20 63 61 6c 6c 20 74 6f 20 5b  failed call to [
375f0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
37600 6e 28 29 5d 29 20 69 73 20 61 20 68 61 72 6d 6c  n()]) is a harml
37610 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e  ess no-op..*/.in
37620 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63  t sqlite3_blob_c
37630 6c 6f 73 65 28 73 71 6c 69 74 65 33 5f 62 6c 6f  lose(sqlite3_blo
37640 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  b *);../*.** CAP
37650 49 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68  I3REF: Return Th
37660 65 20 53 69 7a 65 20 4f 66 20 41 6e 20 4f 70 65  e Size Of An Ope
37670 6e 20 42 4c 4f 42 0a 2a 2a 0a 2a 2a 20 5e 52 65  n BLOB.**.** ^Re
37680 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 69  turns the size i
37690 6e 20 62 79 74 65 73 20 6f 66 20 74 68 65 20 42  n bytes of the B
376a0 4c 4f 42 20 61 63 63 65 73 73 69 62 6c 65 20 76  LOB accessible v
376b0 69 61 20 74 68 65 20 0a 2a 2a 20 73 75 63 63 65  ia the .** succe
376c0 73 73 66 75 6c 6c 79 20 6f 70 65 6e 65 64 20 5b  ssfully opened [
376d0 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 69 6e 20  BLOB handle] in 
376e0 69 74 73 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  its only argumen
376f0 74 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 63 72  t.  ^The.** incr
37700 65 6d 65 6e 74 61 6c 20 62 6c 6f 62 20 49 2f 4f  emental blob I/O
37710 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 6f 6e   routines can on
37720 6c 79 20 72 65 61 64 20 6f 72 20 6f 76 65 72 77  ly read or overw
37730 72 69 74 69 6e 67 20 65 78 69 73 74 69 6e 67 0a  riting existing.
37740 2a 2a 20 62 6c 6f 62 20 63 6f 6e 74 65 6e 74 3b  ** blob content;
37750 20 74 68 65 79 20 63 61 6e 6e 6f 74 20 63 68 61   they cannot cha
37760 6e 67 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  nge the size of 
37770 61 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 54 68  a blob..**.** Th
37780 69 73 20 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20  is routine only 
37790 77 6f 72 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42  works on a [BLOB
377a0 20 68 61 6e 64 6c 65 5d 20 77 68 69 63 68 20 68   handle] which h
377b0 61 73 20 62 65 65 6e 20 63 72 65 61 74 65 64 0a  as been created.
377c0 2a 2a 20 62 79 20 61 20 70 72 69 6f 72 20 73 75  ** by a prior su
377d0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
377e0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
377f0 70 65 6e 28 29 5d 20 61 6e 64 20 77 68 69 63 68  pen()] and which
37800 20 68 61 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e   has not.** been
37810 20 63 6c 6f 73 65 64 20 62 79 20 5b 73 71 6c 69   closed by [sqli
37820 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29  te3_blob_close()
37830 5d 2e 20 20 50 61 73 73 69 6e 67 20 61 6e 79 20  ].  Passing any 
37840 6f 74 68 65 72 20 70 6f 69 6e 74 65 72 20 69 6e  other pointer in
37850 0a 2a 2a 20 74 6f 20 74 68 69 73 20 72 6f 75 74  .** to this rout
37860 69 6e 65 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ine results in u
37870 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
37880 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c  bably undesirabl
37890 65 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2f 0a 69  e behavior..*/.i
378a0 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  nt sqlite3_blob_
378b0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 62 6c  bytes(sqlite3_bl
378c0 6f 62 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ob *);../*.** CA
378d0 50 49 33 52 45 46 3a 20 52 65 61 64 20 44 61 74  PI3REF: Read Dat
378e0 61 20 46 72 6f 6d 20 41 20 42 4c 4f 42 20 49 6e  a From A BLOB In
378f0 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a 0a 2a  crementally.**.*
37900 2a 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f  * ^(This functio
37910 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 61  n is used to rea
37920 64 20 64 61 74 61 20 66 72 6f 6d 20 61 6e 20 6f  d data from an o
37930 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  pen [BLOB handle
37940 5d 20 69 6e 74 6f 20 61 0a 2a 2a 20 63 61 6c 6c  ] into a.** call
37950 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75 66 66  er-supplied buff
37960 65 72 2e 20 4e 20 62 79 74 65 73 20 6f 66 20 64  er. N bytes of d
37970 61 74 61 20 61 72 65 20 63 6f 70 69 65 64 20 69  ata are copied i
37980 6e 74 6f 20 62 75 66 66 65 72 20 5a 0a 2a 2a 20  nto buffer Z.** 
37990 66 72 6f 6d 20 74 68 65 20 6f 70 65 6e 20 42 4c  from the open BL
379a0 4f 42 2c 20 73 74 61 72 74 69 6e 67 20 61 74 20  OB, starting at 
379b0 6f 66 66 73 65 74 20 69 4f 66 66 73 65 74 2e 29  offset iOffset.)
379c0 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 6f 66 66 73  ^.**.** ^If offs
379d0 65 74 20 69 4f 66 66 73 65 74 20 69 73 20 6c 65  et iOffset is le
379e0 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65 73 20  ss than N bytes 
379f0 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f 66 20  from the end of 
37a00 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b 53 51  the BLOB,.** [SQ
37a10 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20 72  LITE_ERROR] is r
37a20 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20 64  eturned and no d
37a30 61 74 61 20 69 73 20 72 65 61 64 2e 20 20 5e 49  ata is read.  ^I
37a40 66 20 4e 20 6f 72 20 69 4f 66 66 73 65 74 20 69  f N or iOffset i
37a50 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 7a  s.** less than z
37a60 65 72 6f 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ero, [SQLITE_ERR
37a70 4f 52 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  OR] is returned 
37a80 61 6e 64 20 6e 6f 20 64 61 74 61 20 69 73 20 72  and no data is r
37a90 65 61 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 69 7a  ead..** ^The siz
37aa0 65 20 6f 66 20 74 68 65 20 62 6c 6f 62 20 28 61  e of the blob (a
37ab0 6e 64 20 68 65 6e 63 65 20 74 68 65 20 6d 61 78  nd hence the max
37ac0 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 4e 2b  imum value of N+
37ad0 69 4f 66 66 73 65 74 29 0a 2a 2a 20 63 61 6e 20  iOffset).** can 
37ae0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
37af0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
37b00 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69  _blob_bytes()] i
37b10 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
37b20 5e 41 6e 20 61 74 74 65 6d 70 74 20 74 6f 20 72  ^An attempt to r
37b30 65 61 64 20 66 72 6f 6d 20 61 6e 20 65 78 70 69  ead from an expi
37b40 72 65 64 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  red [BLOB handle
37b50 5d 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 0a  ] fails with an.
37b60 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 6f 66  ** error code of
37b70 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54 5d 2e   [SQLITE_ABORT].
37b80 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63  .**.** ^(On succ
37b90 65 73 73 2c 20 73 71 6c 69 74 65 33 5f 62 6c 6f  ess, sqlite3_blo
37ba0 62 5f 72 65 61 64 28 29 20 72 65 74 75 72 6e 73  b_read() returns
37bb0 20 53 51 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f   SQLITE_OK..** O
37bc0 74 68 65 72 77 69 73 65 2c 20 61 6e 20 5b 65 72  therwise, an [er
37bd0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20  ror code] or an 
37be0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
37bf0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
37c00 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  d.)^.**.** This 
37c10 72 6f 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72  routine only wor
37c20 6b 73 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61  ks on a [BLOB ha
37c30 6e 64 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20  ndle] which has 
37c40 62 65 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20  been created.** 
37c50 62 79 20 61 20 70 72 69 6f 72 20 73 75 63 63 65  by a prior succe
37c60 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
37c70 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
37c80 28 29 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61  ()] and which ha
37c90 73 20 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c  s not.** been cl
37ca0 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  osed by [sqlite3
37cb0 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20  _blob_close()]. 
37cc0 20 50 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68   Passing any oth
37cd0 65 72 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a  er pointer in.**
37ce0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
37cf0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
37d00 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
37d10 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ly undesirable b
37d20 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53  ehavior..**.** S
37d30 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
37d40 33 5f 62 6c 6f 62 5f 77 72 69 74 65 28 29 5d 2e  3_blob_write()].
37d50 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
37d60 62 6c 6f 62 5f 72 65 61 64 28 73 71 6c 69 74 65  blob_read(sqlite
37d70 33 5f 62 6c 6f 62 20 2a 2c 20 76 6f 69 64 20 2a  3_blob *, void *
37d80 5a 2c 20 69 6e 74 20 4e 2c 20 69 6e 74 20 69 4f  Z, int N, int iO
37d90 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ffset);../*.** C
37da0 41 50 49 33 52 45 46 3a 20 57 72 69 74 65 20 44  API3REF: Write D
37db0 61 74 61 20 49 6e 74 6f 20 41 20 42 4c 4f 42 20  ata Into A BLOB 
37dc0 49 6e 63 72 65 6d 65 6e 74 61 6c 6c 79 0a 2a 2a  Incrementally.**
37dd0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
37de0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 77 72  on is used to wr
37df0 69 74 65 20 64 61 74 61 20 69 6e 74 6f 20 61 6e  ite data into an
37e00 20 6f 70 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64   open [BLOB hand
37e10 6c 65 5d 20 66 72 6f 6d 20 61 0a 2a 2a 20 63 61  le] from a.** ca
37e20 6c 6c 65 72 2d 73 75 70 70 6c 69 65 64 20 62 75  ller-supplied bu
37e30 66 66 65 72 2e 20 5e 4e 20 62 79 74 65 73 20 6f  ffer. ^N bytes o
37e40 66 20 64 61 74 61 20 61 72 65 20 63 6f 70 69 65  f data are copie
37e50 64 20 66 72 6f 6d 20 74 68 65 20 62 75 66 66 65  d from the buffe
37e60 72 20 5a 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  r Z.** into the 
37e70 6f 70 65 6e 20 42 4c 4f 42 2c 20 73 74 61 72 74  open BLOB, start
37e80 69 6e 67 20 61 74 20 6f 66 66 73 65 74 20 69 4f  ing at offset iO
37e90 66 66 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ffset..**.** ^If
37ea0 20 74 68 65 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   the [BLOB handl
37eb0 65 5d 20 70 61 73 73 65 64 20 61 73 20 74 68 65  e] passed as the
37ec0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
37ed0 77 61 73 20 6e 6f 74 20 6f 70 65 6e 65 64 20 66  was not opened f
37ee0 6f 72 0a 2a 2a 20 77 72 69 74 69 6e 67 20 28 74  or.** writing (t
37ef0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
37f00 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
37f10 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 77 61 73 20  lob_open()] was 
37f20 7a 65 72 6f 29 2c 0a 2a 2a 20 74 68 69 73 20 66  zero),.** this f
37f30 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
37f40 5b 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  [SQLITE_READONLY
37f50 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ]..**.** ^This f
37f60 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79  unction may only
37f70 20 6d 6f 64 69 66 79 20 74 68 65 20 63 6f 6e 74   modify the cont
37f80 65 6e 74 73 20 6f 66 20 74 68 65 20 42 4c 4f 42  ents of the BLOB
37f90 3b 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 70  ; it is.** not p
37fa0 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 63 72 65  ossible to incre
37fb0 61 73 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ase the size of 
37fc0 61 20 42 4c 4f 42 20 75 73 69 6e 67 20 74 68 69  a BLOB using thi
37fd0 73 20 41 50 49 2e 0a 2a 2a 20 5e 49 66 20 6f 66  s API..** ^If of
37fe0 66 73 65 74 20 69 4f 66 66 73 65 74 20 69 73 20  fset iOffset is 
37ff0 6c 65 73 73 20 74 68 61 6e 20 4e 20 62 79 74 65  less than N byte
38000 73 20 66 72 6f 6d 20 74 68 65 20 65 6e 64 20 6f  s from the end o
38010 66 20 74 68 65 20 42 4c 4f 42 2c 0a 2a 2a 20 5b  f the BLOB,.** [
38020 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73  SQLITE_ERROR] is
38030 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f   returned and no
38040 20 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e   data is written
38050 2e 20 20 5e 49 66 20 4e 20 69 73 0a 2a 2a 20 6c  .  ^If N is.** l
38060 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 20 5b 53  ess than zero [S
38070 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 73 20  QLITE_ERROR] is 
38080 72 65 74 75 72 6e 65 64 20 61 6e 64 20 6e 6f 20  returned and no 
38090 64 61 74 61 20 69 73 20 77 72 69 74 74 65 6e 2e  data is written.
380a0 0a 2a 2a 20 54 68 65 20 73 69 7a 65 20 6f 66 20  .** The size of 
380b0 74 68 65 20 42 4c 4f 42 20 28 61 6e 64 20 68 65  the BLOB (and he
380c0 6e 63 65 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  nce the maximum 
380d0 76 61 6c 75 65 20 6f 66 20 4e 2b 69 4f 66 66 73  value of N+iOffs
380e0 65 74 29 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65  et).** can be de
380f0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 74  termined using t
38100 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
38110 5f 62 79 74 65 73 28 29 5d 20 69 6e 74 65 72 66  _bytes()] interf
38120 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ace..**.** ^An a
38130 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
38140 74 6f 20 61 6e 20 65 78 70 69 72 65 64 20 5b 42  to an expired [B
38150 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 66 61 69 6c  LOB handle] fail
38160 73 20 77 69 74 68 20 61 6e 0a 2a 2a 20 65 72 72  s with an.** err
38170 6f 72 20 63 6f 64 65 20 6f 66 20 5b 53 51 4c 49  or code of [SQLI
38180 54 45 5f 41 42 4f 52 54 5d 2e 20 20 5e 57 72 69  TE_ABORT].  ^Wri
38190 74 65 73 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  tes to the BLOB 
381a0 74 68 61 74 20 6f 63 63 75 72 72 65 64 0a 2a 2a  that occurred.**
381b0 20 62 65 66 6f 72 65 20 74 68 65 20 5b 42 4c 4f   before the [BLO
381c0 42 20 68 61 6e 64 6c 65 5d 20 65 78 70 69 72 65  B handle] expire
381d0 64 20 61 72 65 20 6e 6f 74 20 72 6f 6c 6c 65 64  d are not rolled
381e0 20 62 61 63 6b 20 62 79 20 74 68 65 0a 2a 2a 20   back by the.** 
381f0 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68  expiration of th
38200 65 20 68 61 6e 64 6c 65 2c 20 74 68 6f 75 67 68  e handle, though
38210 20 6f 66 20 63 6f 75 72 73 65 20 74 68 6f 73 65   of course those
38220 20 63 68 61 6e 67 65 73 20 6d 69 67 68 74 0a 2a   changes might.*
38230 2a 20 68 61 76 65 20 62 65 65 6e 20 6f 76 65 72  * have been over
38240 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 73  written by the s
38250 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 65 78  tatement that ex
38260 70 69 72 65 64 20 74 68 65 20 42 4c 4f 42 20 68  pired the BLOB h
38270 61 6e 64 6c 65 0a 2a 2a 20 6f 72 20 62 79 20 6f  andle.** or by o
38280 74 68 65 72 20 69 6e 64 65 70 65 6e 64 65 6e 74  ther independent
38290 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
382a0 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73 2c  ** ^(On success,
382b0 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72   sqlite3_blob_wr
382c0 69 74 65 28 29 20 72 65 74 75 72 6e 73 20 53 51  ite() returns SQ
382d0 4c 49 54 45 5f 4f 4b 2e 0a 2a 2a 20 4f 74 68 65  LITE_OK..** Othe
382e0 72 77 69 73 65 2c 20 61 6e 20 20 5b 65 72 72 6f  rwise, an  [erro
382f0 72 20 63 6f 64 65 5d 20 6f 72 20 61 6e 20 5b 65  r code] or an [e
38300 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
38310 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
38320 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  )^.**.** This ro
38330 75 74 69 6e 65 20 6f 6e 6c 79 20 77 6f 72 6b 73  utine only works
38340 20 6f 6e 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64   on a [BLOB hand
38350 6c 65 5d 20 77 68 69 63 68 20 68 61 73 20 62 65  le] which has be
38360 65 6e 20 63 72 65 61 74 65 64 0a 2a 2a 20 62 79  en created.** by
38370 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73   a prior success
38380 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
38390 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
383a0 5d 20 61 6e 64 20 77 68 69 63 68 20 68 61 73 20  ] and which has 
383b0 6e 6f 74 0a 2a 2a 20 62 65 65 6e 20 63 6c 6f 73  not.** been clos
383c0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
383d0 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 20 20 50  lob_close()].  P
383e0 61 73 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  assing any other
383f0 20 70 6f 69 6e 74 65 72 20 69 6e 0a 2a 2a 20 74   pointer in.** t
38400 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  o this routine r
38410 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
38420 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
38430 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
38440 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  avior..**.** See
38450 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
38460 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2e 0a 2a 2f  blob_read()]..*/
38470 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f  .int sqlite3_blo
38480 62 5f 77 72 69 74 65 28 73 71 6c 69 74 65 33 5f  b_write(sqlite3_
38490 62 6c 6f 62 20 2a 2c 20 63 6f 6e 73 74 20 76 6f  blob *, const vo
384a0 69 64 20 2a 7a 2c 20 69 6e 74 20 6e 2c 20 69 6e  id *z, int n, in
384b0 74 20 69 4f 66 66 73 65 74 29 3b 0a 0a 2f 2a 0a  t iOffset);../*.
384c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
384d0 74 75 61 6c 20 46 69 6c 65 20 53 79 73 74 65 6d  tual File System
384e0 20 4f 62 6a 65 63 74 73 0a 2a 2a 0a 2a 2a 20 41   Objects.**.** A
384f0 20 76 69 72 74 75 61 6c 20 66 69 6c 65 73 79 73   virtual filesys
38500 74 65 6d 20 28 56 46 53 29 20 69 73 20 61 6e 20  tem (VFS) is an 
38510 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
38520 6a 65 63 74 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ject.** that SQL
38530 69 74 65 20 75 73 65 73 20 74 6f 20 69 6e 74 65  ite uses to inte
38540 72 61 63 74 0a 2a 2a 20 77 69 74 68 20 74 68 65  ract.** with the
38550 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
38560 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 4d  ating system.  M
38570 6f 73 74 20 53 51 4c 69 74 65 20 62 75 69 6c 64  ost SQLite build
38580 73 20 63 6f 6d 65 20 77 69 74 68 20 61 0a 2a 2a  s come with a.**
38590 20 73 69 6e 67 6c 65 20 64 65 66 61 75 6c 74 20   single default 
385a0 56 46 53 20 74 68 61 74 20 69 73 20 61 70 70 72  VFS that is appr
385b0 6f 70 72 69 61 74 65 20 66 6f 72 20 74 68 65 20  opriate for the 
385c0 68 6f 73 74 20 63 6f 6d 70 75 74 65 72 2e 0a 2a  host computer..*
385d0 2a 20 4e 65 77 20 56 46 53 65 73 20 63 61 6e 20  * New VFSes can 
385e0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 61 6e  be registered an
385f0 64 20 65 78 69 73 74 69 6e 67 20 56 46 53 65 73  d existing VFSes
38600 20 63 61 6e 20 62 65 20 75 6e 72 65 67 69 73 74   can be unregist
38610 65 72 65 64 2e 0a 2a 2a 20 54 68 65 20 66 6f 6c  ered..** The fol
38620 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
38630 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 2e 0a  s are provided..
38640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
38650 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 20 69 6e  e3_vfs_find() in
38660 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
38670 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 56  a pointer to a V
38680 46 53 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  FS given its nam
38690 65 2e 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65  e..** ^Names are
386a0 20 63 61 73 65 20 73 65 6e 73 69 74 69 76 65 2e   case sensitive.
386b0 0a 2a 2a 20 5e 4e 61 6d 65 73 20 61 72 65 20 7a  .** ^Names are z
386c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
386d0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
386e0 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f   ^If there is no
386f0 20 6d 61 74 63 68 2c 20 61 20 4e 55 4c 4c 20 70   match, a NULL p
38700 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
38710 65 64 2e 0a 2a 2a 20 5e 49 66 20 7a 56 66 73 4e  ed..** ^If zVfsN
38720 61 6d 65 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ame is NULL then
38730 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
38740 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
38750 0a 2a 2a 20 5e 4e 65 77 20 56 46 53 65 73 20 61  .** ^New VFSes a
38760 72 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  re registered wi
38770 74 68 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  th sqlite3_vfs_r
38780 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 20 5e 45  egister()..** ^E
38790 61 63 68 20 6e 65 77 20 56 46 53 20 62 65 63 6f  ach new VFS beco
387a0 6d 65 73 20 74 68 65 20 64 65 66 61 75 6c 74 20  mes the default 
387b0 56 46 53 20 69 66 20 74 68 65 20 6d 61 6b 65 44  VFS if the makeD
387c0 66 6c 74 20 66 6c 61 67 20 69 73 20 73 65 74 2e  flt flag is set.
387d0 0a 2a 2a 20 5e 54 68 65 20 73 61 6d 65 20 56 46  .** ^The same VF
387e0 53 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  S can be registe
387f0 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
38800 65 73 20 77 69 74 68 6f 75 74 20 69 6e 6a 75 72  es without injur
38810 79 2e 0a 2a 2a 20 5e 54 6f 20 6d 61 6b 65 20 61  y..** ^To make a
38820 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20 69  n existing VFS i
38830 6e 74 6f 20 74 68 65 20 64 65 66 61 75 6c 74 20  nto the default 
38840 56 46 53 2c 20 72 65 67 69 73 74 65 72 20 69 74  VFS, register it
38850 20 61 67 61 69 6e 0a 2a 2a 20 77 69 74 68 20 74   again.** with t
38860 68 65 20 6d 61 6b 65 44 66 6c 74 20 66 6c 61 67  he makeDflt flag
38870 20 73 65 74 2e 20 20 49 66 20 74 77 6f 20 64 69   set.  If two di
38880 66 66 65 72 65 6e 74 20 56 46 53 65 73 20 77 69  fferent VFSes wi
38890 74 68 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 6e  th the.** same n
388a0 61 6d 65 20 61 72 65 20 72 65 67 69 73 74 65 72  ame are register
388b0 65 64 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ed, the behavior
388c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
388d0 49 66 20 61 0a 2a 2a 20 56 46 53 20 69 73 20 72  If a.** VFS is r
388e0 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 61  egistere