/ Hex Artifact Content
Login

Artifact 3fef17a4201b068291da874b42599b9e61c0cf68:


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 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
41d0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
41e0: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
41f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4200: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4210: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4220: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4230: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4250: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4260: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4270: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
4280: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4290: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
42a0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
42b0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
42c0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
42d0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
42e0: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
42f0: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4310: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4320: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4330: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4350: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4360: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4370: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
4380: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
4390: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
43a0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
43b0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
43c0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
43f0: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4400: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4410: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4420: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4430: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4440: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4450: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4460: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4470: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
4480: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
4490: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
44a0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
44b0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
44c0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
44d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
44e0: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
44f0: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4500: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4510: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4520: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4530: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4540: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4550: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4560: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4570: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
4580: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
4590: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
45a0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
45b0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
45c0: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
45d0: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
45e0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
45f0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4600: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4610: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4620: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4630: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4640: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4650: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4660: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4670: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4680: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4690: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
46a0: 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d  nded error code}
46b0: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
46c0: 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f   codes}.** KEYWO
46d0: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
46e0: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74  esult code} {ext
46f0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4700: 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  es}.**.** In its
4710: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4720: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4730: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4740: 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74  rn one of 26 int
4750: 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  eger.** [SQLITE_
4760: 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  OK | result code
4770: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
4780: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
4790: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
47a0: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
47b0: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
47c0: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
47d0: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
47e0: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
47f0: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
4800: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
4810: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
4820: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
4830: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
4840: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
4850: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
4860: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e  version 3.3.8 an
4870: 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65  d later) include
4880: 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20  .** support for 
4890: 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c  additional resul
48a0: 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f  t codes that pro
48b0: 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c  vide more detail
48c0: 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ed information.*
48d0: 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20  * about errors. 
48e0: 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
48f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e  ult codes are en
4900: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4910: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4920: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4930: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4940: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4950: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4960: 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a  des()] API..**.*
4970: 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76  * Some of the av
4980: 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64  ailable extended
4990: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49a0: 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a  e listed here..*
49b0: 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74  * One may expect
49c0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
49d0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
49e0: 6f 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70  odes will be exp
49f0: 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65  and.** over time
4a00: 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
4a10: 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72   uses extended r
4a20: 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75  esult codes shou
4a30: 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20  ld expect.** to 
4a40: 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63  see new result c
4a50: 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  odes in future r
4a60: 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
4a70: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  e..**.** The SQL
4a80: 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f  ITE_OK result co
4a90: 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65  de will never be
4aa0: 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77   extended.  It w
4ab0: 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  ill always.** be
4ac0: 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a   exactly zero..*
4ad0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ae0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4af0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4b00: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b20: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4b30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4b40: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4b50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4b60: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4b70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4b80: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ba0: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4bb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4bc0: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4bd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4be0: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4bf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4c00: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4c20: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4c40: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4c50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4c60: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4c70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4c80: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4c90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ca0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
4cb0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4cc0: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
4cd0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
4ce0: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
4cf0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4d00: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
4d10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
4d20: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
4d30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d40: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
4d50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
4d60: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
4d70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4d80: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
4d90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
4da0: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
4db0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4dc0: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
4dd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
4de0: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
4df0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e00: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
4e10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
4e20: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
4e30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e40: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
4e50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
4e60: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
4e70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4e80: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
4e90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
4ea0: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
4eb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4ec0: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
4ed0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f00: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
4f10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f20: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
4f30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f40: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
4f50: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4f60: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
4f70: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f80: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
4f90: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
4fa0: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
4fb0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fc0: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
4fd0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
4fe0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
4ff0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
5000: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5010: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
5020: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
5030: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5040: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5050: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5060: 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20  EN_NOTEMPDIR    
5070: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5080: 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  EN | (1<<8))../*
5090: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
50a0: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
50b0: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
50c0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
50d0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
50e0: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
50f0: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5100: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5110: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5120: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5130: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5140: 72 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  r to the xOpen m
5150: 65 74 68 6f 64 20 6f 66 20 74 68 65 0a 2a 2a 20  ethod of the.** 
5160: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
5170: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5180: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
5190: 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78  DONLY         0x
51a0: 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20  00000001  /* Ok 
51b0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
51c0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
51d0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
51e0: 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78  DWRITE        0x
51f0: 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20  00000002  /* Ok 
5200: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5210: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5220: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
5230: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78  ATE           0x
5240: 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20  00000004  /* Ok 
5250: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5260: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5270: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c   SQLITE_OPEN_DEL
5280: 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78  ETEONCLOSE    0x
5290: 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53  00000008  /* VFS
52a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
52b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
52c0: 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78  LUSIVE        0x
52d0: 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53  00000010  /* VFS
52e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
52f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54   SQLITE_OPEN_AUT
5300: 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78  OPROXY        0x
5310: 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53  00000020  /* VFS
5320: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5330: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5340: 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  N_DB          0x
5350: 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53  00000100  /* VFS
5360: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5370: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5380: 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78  P_DB          0x
5390: 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53  00000200  /* VFS
53a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
53b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41   SQLITE_OPEN_TRA
53c0: 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78  NSIENT_DB     0x
53d0: 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53  00000400  /* VFS
53e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
53f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49   SQLITE_OPEN_MAI
5400: 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  N_JOURNAL     0x
5410: 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53  00000800  /* VFS
5420: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5430: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d   SQLITE_OPEN_TEM
5440: 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78  P_JOURNAL     0x
5450: 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53  00001000  /* VFS
5460: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
5470: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42   SQLITE_OPEN_SUB
5480: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78  JOURNAL       0x
5490: 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53  00002000  /* VFS
54a0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
54b0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53   SQLITE_OPEN_MAS
54c0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78  TER_JOURNAL   0x
54d0: 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53  00004000  /* VFS
54e0: 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65   only */.#define
54f0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d   SQLITE_OPEN_NOM
5500: 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78  UTEX          0x
5510: 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20  00008000  /* Ok 
5520: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5530: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5540: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c   SQLITE_OPEN_FUL
5550: 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78  LMUTEX        0x
5560: 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00010000  /* Ok 
5570: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5580: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5590: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
55a0: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78  REDCACHE      0x
55b0: 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00020000  /* Ok 
55c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
55d0: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
55e0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
55f0: 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78  VATECACHE     0x
5600: 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20  00040000  /* Ok 
5610: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
5620: 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  _v2() */.#define
5630: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c   SQLITE_OPEN_WAL
5640: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5650: 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53  00080000  /* VFS
5660: 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73   only */../* Res
5670: 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20  erved:          
5680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5690: 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a  x00F00000 */../*
56a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
56b0: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
56c0: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
56d0: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
56e0: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
56f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5700: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
5710: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
5720: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
5730: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
5740: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
5750: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
5760: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
5770: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
5780: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
5790: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
57a0: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
57b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
57c0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
57d0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
57e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
57f0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
5800: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
5810: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
5820: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
5830: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5840: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
5850: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
5860: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
5870: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
5880: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
5890: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
58a0: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
58b0: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
58c0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
58d0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
58e0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
58f0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
5900: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
5910: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
5920: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
5930: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
5940: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
5950: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
5960: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
5970: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
5980: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
5990: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
59a0: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
59b0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
59c0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
59d0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
59e0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
59f0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
5a00: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
5a10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5a20: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
5a30: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5a40: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5a50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5a60: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
5a70: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
5a80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5a90: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
5aa0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ab0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
5ac0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5ad0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
5ae0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
5af0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5b00: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
5b10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5b20: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
5b30: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
5b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5b50: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
5b60: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5b70: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
5b80: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5ba0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
5bb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5bc0: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
5bd0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5be0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
5bf0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
5c00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5c10: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
5c20: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5c30: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5c40: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
5c50: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
5c60: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
5c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c80: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
5c90: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
5ca0: 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
5cb0: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
5cc0: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
5cd0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
5ce0: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
5cf0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
5d00: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
5d10: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
5d20: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
5d30: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
5d40: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
5d50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5d60: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
5d70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d80: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
5d90: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
5da0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
5db0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
5dc0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
5dd0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
5de0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5df0: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
5e00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e10: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
5e20: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
5e30: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
5e40: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
5e50: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
5e60: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
5e70: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
5e80: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5e90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5ea0: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
5eb0: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
5ec0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5ed0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5ee0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
5ef0: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
5f00: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5f10: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
5f20: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
5f30: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
5f40: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
5f50: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
5f60: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
5f70: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
5f80: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
5f90: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
5fa0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
5fb0: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
5fc0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
5fd0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
5fe0: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
5ff0: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
6000: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
6010: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
6020: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
6030: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
6040: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
6050: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
6060: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
6070: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
6080: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
6090: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
60a0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
60b0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
60c0: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
60d0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
60e0: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
60f0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
6100: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
6110: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
6120: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
6130: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
6140: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
6150: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
6160: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
6170: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
6180: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
6190: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
61a0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
61b0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
61c0: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
61d0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
61e0: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
61f0: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
6200: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
6210: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
6220: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
6230: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
6240: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
6250: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
6260: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
6270: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
6280: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
6290: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
62a0: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
62b0: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
62c0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
62d0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
62e0: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
62f0: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
6300: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
6310: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
6320: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
6330: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
6340: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6350: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
6360: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6370: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
6380: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
6390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
63a0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
63b0: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
63c0: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
63d0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
63e0: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
63f0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
6400: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
6410: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
6420: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
6430: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
6440: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
6450: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
6460: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
6470: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
6480: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
6490: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
64a0: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
64b0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
64c0: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
64d0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
64e0: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
64f0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
6500: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6510: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
6520: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
6530: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
6540: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
6550: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
6560: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
6570: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
6580: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
6590: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
65a0: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
65b0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
65c0: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
65d0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
65e0: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
65f0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6600: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6610: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
6620: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
6630: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
6640: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
6650: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
6660: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  en method popula
6670: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
6680: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
6690: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
66a0: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
66b0: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
66c0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
66d0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
66e0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
66f0: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
6700: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
6710: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
6720: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
6730: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
6740: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
6750: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
6760: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
6770: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6780: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
6790: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
67a0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
67b0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
67c0: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
67d0: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
67e0: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
67f0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
6800: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
6810: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
6820: 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65 6e  ven if the xOpen
6830: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
6840: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
6850: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
6860: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
6870: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6880: 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a   a failed xOpen.
6890: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78 4f  ** is for the xO
68a0: 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20 73  pen to set the s
68b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
68c0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20  hods element to 
68d0: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
68e0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
68f0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
6900: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
6910: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
6920: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
6930: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
6940: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
6950: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
6960: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
6970: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
6980: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
6990: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
69a0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
69b0: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
69c0: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
69d0: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
69e0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
69f0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
6a00: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
6a10: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
6a20: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6a30: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
6a40: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
6a50: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
6a60: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6a70: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
6a80: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
6a90: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
6aa0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6ab0: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
6ac0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6ad0: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
6ae0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
6af0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
6b00: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
6b10: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
6b20: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
6b30: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
6b40: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
6b50: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
6b60: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
6b70: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
6b80: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
6b90: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
6ba0: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
6bb0: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
6bc0: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
6bd0: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
6be0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
6bf0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
6c00: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
6c10: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
6c20: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
6c30: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
6c40: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
6c50: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
6c60: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
6c70: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
6c80: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
6c90: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6ca0: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
6cb0: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
6cc0: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
6cd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6ce0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
6cf0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
6d00: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
6d10: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
6d20: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
6d30: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
6d40: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
6d50: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
6d60: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
6d70: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
6d80: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
6d90: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
6da0: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
6db0: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
6dc0: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
6dd0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
6de0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
6df0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
6e00: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
6e10: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
6e20: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
6e30: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
6e40: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
6e50: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
6e60: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
6e70: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
6e80: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
6e90: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
6ea0: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
6eb0: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
6ec0: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
6ed0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
6ee0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
6ef0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
6f00: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
6f10: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
6f20: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
6f30: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
6f40: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
6f50: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
6f60: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6f70: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
6f80: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
6f90: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
6fa0: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
6fb0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
6fc0: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
6fd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
6fe0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
6ff0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7000: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7010: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
7020: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
7030: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
7040: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
7050: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
7060: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
7070: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
7080: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
7090: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
70a0: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
70b0: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
70c0: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
70d0: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
70e0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
70f0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7100: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7110: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7120: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7130: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
7140: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
7150: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
7160: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7170: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7180: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7190: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
71a0: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
71b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
71c0: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
71d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
71e0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
71f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7200: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7210: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7220: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7230: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7240: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
7250: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7260: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
7270: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7280: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7290: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
72a0: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
72b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
72c0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
72d0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
72e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
72f0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7300: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
7310: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
7320: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
7330: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7340: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
7350: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
7360: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
7370: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
7380: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
7390: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
73a0: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
73b0: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
73c0: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
73d0: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
73e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
73f0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
7400: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
7410: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
7420: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
7430: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
7440: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
7450: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
7460: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
7470: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
7480: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
7490: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
74a0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
74b0: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
74c0: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
74d0: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
74e0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
74f0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
7500: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
7510: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
7520: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
7530: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
7540: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
7550: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
7560: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
7570: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
7580: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
7590: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
75a0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
75b0: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
75c0: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
75d0: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
75e0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
75f0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
7600: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
7610: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
7620: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
7630: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7640: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
7650: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7660: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
7670: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
7680: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
7690: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
76a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
76b0: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
76c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
76d0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
76e0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
76f0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
7700: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
7710: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
7720: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
7730: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
7740: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
7750: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
7760: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
7770: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
7780: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
7790: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
77a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
77b0: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
77c0: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
77d0: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
77e0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
77f0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
7800: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
7810: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7820: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
7830: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
7840: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7850: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
7860: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
7870: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
7880: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
7890: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
78a0: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
78b0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
78c0: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
78d0: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
78e0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
78f0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7900: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7910: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
7920: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
7930: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7940: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
7950: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
7960: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
7970: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
7980: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
7990: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
79a0: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
79b0: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
79c0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
79d0: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
79e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
79f0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
7a00: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7a10: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7a20: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
7a30: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
7a40: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
7a50: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
7a60: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
7a70: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
7a80: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
7a90: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
7aa0: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
7ab0: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
7ac0: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
7ad0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
7ae0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
7af0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7b00: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
7b10: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
7b20: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
7b30: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
7b40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
7b50: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
7b60: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
7b70: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
7b80: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
7b90: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
7ba0: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
7bb0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
7bc0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
7bd0: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
7be0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
7bf0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7c00: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
7c10: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
7c20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7c30: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
7c40: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7c50: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
7c60: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
7c70: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
7c80: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
7c90: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
7ca0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
7cb0: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
7cc0: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
7cd0: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
7ce0: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
7cf0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
7d00: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
7d10: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
7d20: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
7d30: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
7d40: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
7d50: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
7d60: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
7d70: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
7d80: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
7d90: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
7da0: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
7db0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
7dc0: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
7dd0: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
7de0: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
7df0: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
7e00: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
7e10: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
7e20: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
7e30: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
7e40: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
7e50: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
7e60: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
7e70: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
7e80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
7e90: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
7ea0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
7eb0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
7ec0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
7ed0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
7ee0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
7ef0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
7f00: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
7f10: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
7f20: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
7f30: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
7f40: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
7f50: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
7f60: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
7f70: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
7f80: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
7f90: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
7fa0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
7fb0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
7fc0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
7fd0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
7fe0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
7ff0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8000: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8010: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8020: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8030: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8040: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
8050: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ems..**.** The [
8060: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
8070: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
8080: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
8090: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
80a0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
80b0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
80c0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
80d0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
80e0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
80f0: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
8100: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8110: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
8120: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
8130: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
8140: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ..**.** ^(The [S
8150: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
8160: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
8170: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
8180: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
8190: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
81a0: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
81b0: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
81c0: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
81d0: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
81e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
81f0: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
8200: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
8210: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
8220: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8230: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
8240: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
8250: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
8260: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
8270: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
8280: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
8290: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
82a0: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
82b0: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
82c0: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
82d0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
82e0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
82f0: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
8300: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
8310: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
8320: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
8330: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
8340: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
8350: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
8360: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
8370: 65 63 69 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a  ecilized VFSes.*
8380: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  * that do requir
8390: 65 20 69 74 2e 20 20 0a 2a 2f 0a 23 64 65 66 69  e it.  .*/.#defi
83a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
83b0: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
83c0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
83d0: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
83e0: 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 69  ILE      2.#defi
83f0: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
8400: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
8410: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
8420: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
8430: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
8440: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8450: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
8460: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
8470: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
8480: 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66 69  ZE       6.#defi
8490: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
84a0: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
84b0: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
84c0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
84d0: 54 54 45 44 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  TTED     8.../*.
84e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
84f0: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
8500: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
8510: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
8520: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
8530: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
8540: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
8550: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
8560: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
8570: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
8580: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
8590: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
85a0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
85b0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
85c0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
85d0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
85e0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
85f0: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
8600: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
8610: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
8620: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
8630: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
8640: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
8650: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
8660: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8670: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
8680: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
8690: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
86a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
86b0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
86c0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
86d0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
86e0: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
86f0: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8700: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8710: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
8720: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
8730: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
8740: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
8750: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
8760: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
8770: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
8780: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
8790: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
87a0: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
87b0: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
87c0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
87d0: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
87e0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
87f0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
8800: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
8810: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
8820: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
8830: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
8840: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
8850: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
8860: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
8870: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
8880: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
8890: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
88a0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
88b0: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
88c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
88d0: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
88e0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
88f0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
8900: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
8910: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
8920: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
8930: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
8940: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
8950: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
8960: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
8970: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
8980: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
8990: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
89a0: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
89b0: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
89c0: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
89d0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
89e0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
89f0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
8a00: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
8a10: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
8a20: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
8a30: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
8a40: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
8a50: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
8a60: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
8a70: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
8a80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8a90: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
8aa0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8ab0: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
8ac0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
8ad0: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
8ae0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
8af0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
8b00: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8b10: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8b20: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8b30: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8b40: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8b50: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8b60: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8b70: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8b80: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8b90: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
8ba0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
8bb0: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
8bc0: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
8bd0: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
8be0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
8bf0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
8c00: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8c10: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8c20: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8c30: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8c40: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8c50: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8c60: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8c70: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  **.** ^SQLite gu
8c80: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
8c90: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
8ca0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
8cb0: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
8cc0: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
8cd0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
8ce0: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
8cf0: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
8d00: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
8d10: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
8d20: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
8d30: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
8d40: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
8d50: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
8d60: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
8d70: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
8d80: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
8d90: 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72  ** 10 alphanumer
8da0: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
8db0: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
8dc0: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
8dd0: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
8de0: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
8df0: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
8e00: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
8e10: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
8e20: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
8e30: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
8e40: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
8e50: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
8e60: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
8e70: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
8e80: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
8e90: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
8ea0: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
8eb0: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
8ec0: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
8ed0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
8ee0: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
8ef0: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
8f00: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
8f10: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
8f20: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
8f30: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
8f40: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
8f50: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
8f60: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
8f70: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
8f80: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
8f90: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
8fa0: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
8fb0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
8fc0: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
8fd0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
8fe0: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
8ff0: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
9000: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
9010: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
9020: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
9030: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
9040: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
9050: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
9060: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
9070: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
9080: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
9090: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
90a0: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
90b0: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
90c0: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
90d0: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
90e0: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
90f0: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
9100: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
9110: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
9120: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
9130: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
9140: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
9150: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
9160: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
9170: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
9180: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
9190: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
91a0: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
91b0: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
91c0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
91d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
91e0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
91f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
9200: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
9210: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
9220: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
9230: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
9240: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
9250: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
9260: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
9270: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9280: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
9290: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
92a0: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
92b0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
92c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
92d0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
92e0: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
92f0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
9300: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
9310: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
9320: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
9330: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
9340: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
9350: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
9360: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
9370: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
9380: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
9390: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
93a0: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
93b0: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
93c0: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
93d0: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
93e0: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
93f0: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
9400: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
9410: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
9420: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
9430: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
9440: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
9450: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
9460: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
9470: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
9480: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
9490: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
94a0: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
94b0: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
94c0: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
94d0: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
94e0: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
94f0: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
9500: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
9510: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
9520: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
9530: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
9540: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
9550: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
9560: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
9570: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
9580: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
9590: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
95a0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
95b0: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
95c0: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
95d0: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
95e0: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
95f0: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
9600: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
9610: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
9620: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
9630: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
9640: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
9650: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
9660: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
9670: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
9680: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
9690: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
96a0: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
96b0: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
96c0: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
96d0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
96e0: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
96f0: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
9700: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
9710: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
9720: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
9730: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
9740: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
9750: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
9760: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
9770: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
9780: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9790: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
97a0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
97b0: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
97c0: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
97d0: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
97e0: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
97f0: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
9800: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
9810: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
9820: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
9830: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
9840: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
9850: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
9860: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
9870: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
9880: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
9890: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
98a0: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
98b0: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
98c0: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
98d0: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
98e0: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
98f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
9900: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
9910: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
9920: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
9930: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
9940: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
9950: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
9960: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
9970: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
9980: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
9990: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
99a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
99b0: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
99c0: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
99d0: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
99e0: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
99f0: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
9a00: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
9a10: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
9a20: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
9a30: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
9a40: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
9a50: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
9a60: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
9a70: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
9a80: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  en call..**.** ^
9a90: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
9aa0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
9ab0: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
9ac0: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
9ad0: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
9ae0: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
9af0: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
9b00: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9b10: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
9b20: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
9b30: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
9b40: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
9b50: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
9b60: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
9b70: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
9b80: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
9b90: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
9ba0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
9bb0: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
9bc0: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
9bd0: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
9be0: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
9bf0: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
9c00: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
9c10: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
9c20: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
9c30: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
9c40: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
9c50: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
9c60: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
9c70: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
9c80: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
9c90: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
9ca0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
9cb0: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
9cc0: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
9cd0: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
9ce0: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
9cf0: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
9d00: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
9d10: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
9d20: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
9d30: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
9d40: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
9d50: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
9d60: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
9d70: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
9d80: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
9d90: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
9da0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
9db0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
9dc0: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
9dd0: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
9de0: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
9df0: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
9e00: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
9e10: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
9e20: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
9e30: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
9e40: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
9e50: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
9e60: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
9e70: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
9e80: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
9e90: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
9ea0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
9eb0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
9ec0: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
9ed0: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
9ee0: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
9ef0: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
9f00: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
9f10: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
9f20: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
9f30: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
9f40: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
9f50: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
9f60: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
9f70: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
9f80: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
9f90: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
9fa0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
9fb0: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
9fc0: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
9fd0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
9fe0: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
9ff0: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
a000: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
a010: 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38 36   multipled by 86
a020: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
a030: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
a040: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
a050: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
a060: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
a070: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
a080: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
a090: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
a0a0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
a0b0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
a0c0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
a0d0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
a0e0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
a0f0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
a100: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
a110: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
a120: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
a130: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
a140: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
a150: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
a160: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
a170: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
a180: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
a190: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
a1a0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
a1b0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
a1c0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
a1d0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
a1e0: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
a1f0: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
a200: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
a210: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
a220: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
a230: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
a240: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
a250: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
a260: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
a270: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
a280: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
a290: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
a2a0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
a2b0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
a2c0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
a2d0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
a2e0: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
a2f0: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
a300: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
a310: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
a320: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
a330: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
a340: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
a350: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
a360: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
a370: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
a380: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
a390: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
a3a0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
a3b0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
a3c0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
a3d0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
a3e0: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
a3f0: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
a400: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
a410: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
a420: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
a430: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
a440: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
a450: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
a460: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
a470: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
a480: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
a490: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
a4a0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
a4b0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
a4c0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
a4d0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
a4e0: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
a4f0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
a500: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
a510: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
a520: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
a530: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
a540: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
a550: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
a560: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
a570: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
a580: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
a590: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
a5a0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
a5b0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
a5c0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
a5d0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
a5e0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
a5f0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
a600: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
a610: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
a620: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
a630: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
a640: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
a650: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
a660: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
a670: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
a680: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
a690: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
a6a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
a6b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
a6c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
a6d0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
a6e0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
a6f0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
a700: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
a710: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
a720: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
a730: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
a740: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
a750: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
a760: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
a770: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
a780: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
a790: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
a7a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
a7b0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
a7c0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
a7d0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
a7e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
a7f0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
a800: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
a810: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
a820: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
a830: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
a840: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
a850: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
a860: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
a870: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
a880: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
a890: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
a8a0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
a8b0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
a8c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
a8d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
a8e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
a8f0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
a900: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
a910: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
a920: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
a930: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
a940: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
a950: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
a960: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
a970: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
a980: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
a990: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
a9a0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
a9b0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
a9c0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
a9d0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
a9e0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
a9f0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
aa00: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
aa10: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
aa20: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
aa30: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
aa40: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
aa50: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
aa60: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
aa70: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
aa80: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
aa90: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
aaa0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
aab0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
aac0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
aad0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
aae0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
aaf0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
ab00: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
ab10: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
ab20: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
ab30: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ab40: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ab50: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
ab60: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
ab70: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
ab80: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
ab90: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
aba0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
abb0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
abc0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
abd0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
abe0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
abf0: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
ac00: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
ac10: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
ac20: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
ac30: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
ac40: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
ac50: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
ac60: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
ac70: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
ac80: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
ac90: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
aca0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
acb0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
acc0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
acd0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
ace0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
acf0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
ad00: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
ad10: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
ad20: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
ad30: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
ad40: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ad50: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
ad60: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ad70: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
ad80: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ad90: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
ada0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
adb0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
adc0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
add0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
ade0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
adf0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
ae00: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
ae10: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
ae20: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
ae30: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
ae40: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
ae50: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
ae60: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
ae70: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
ae80: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
ae90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
aea0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
aeb0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
aec0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
aed0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
aee0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
aef0: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
af00: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
af10: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
af20: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
af30: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
af40: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
af50: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
af60: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
af70: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
af80: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
af90: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
afa0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
afb0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
afc0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
afd0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
afe0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
aff0: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
b000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
b010: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
b020: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b030: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
b040: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
b050: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
b060: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
b070: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
b080: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
b090: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
b0a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b0b0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
b0c0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
b0d0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
b0e0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
b0f0: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
b100: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
b110: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
b120: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
b130: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
b140: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
b150: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
b160: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
b170: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
b180: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
b190: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
b1a0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
b1b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
b1c0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
b1d0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
b1e0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
b1f0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
b200: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
b210: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
b220: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
b230: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
b240: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
b250: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
b260: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
b270: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
b280: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
b290: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
b2a0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
b2b0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
b2c0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
b2d0: 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73  en no the corres
b2e0: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
b2f0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
b300: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
b310: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
b320: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
b330: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
b340: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
b350: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
b360: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
b370: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
b380: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
b390: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
b3a0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
b3b0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
b3c0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
b3d0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
b3e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
b3f0: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
b400: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
b410: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
b420: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
b430: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
b440: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
b450: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
b460: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
b470: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
b480: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
b490: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
b4a0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
b4b0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
b4c0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
b4d0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
b4e0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
b4f0: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
b500: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
b510: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
b520: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b530: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
b540: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
b550: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
b560: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
b570: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
b580: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
b590: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
b5a0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
b5b0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
b5c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
b5d0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
b5e0: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
b5f0: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
b600: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
b610: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
b620: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
b630: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
b640: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
b650: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
b660: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
b670: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
b680: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
b690: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
b6a0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
b6b0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
b6c0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
b6d0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
b6e0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
b6f0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
b700: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b710: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
b720: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
b730: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
b740: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
b750: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
b760: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
b770: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
b780: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
b790: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
b7a0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
b7b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
b7c0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
b7d0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
b7e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
b7f0: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
b800: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
b810: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
b820: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
b830: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
b840: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
b850: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
b860: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
b870: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
b880: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b890: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
b8a0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
b8b0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
b8c0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
b8d0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
b8e0: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
b8f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
b900: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
b910: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
b920: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b930: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
b940: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
b950: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
b960: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
b970: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
b980: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
b990: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
b9a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b9b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
b9c0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
b9d0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b9e0: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
b9f0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
ba00: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
ba10: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
ba20: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
ba30: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
ba40: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
ba50: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
ba60: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
ba70: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
ba80: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
ba90: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
baa0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
bab0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
bac0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
bad0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
bae0: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
baf0: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
bb00: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
bb10: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
bb20: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
bb30: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
bb40: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
bb50: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
bb60: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
bb70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
bb80: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
bb90: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
bba0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
bbb0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
bbc0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bbd0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
bbe0: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
bbf0: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
bc00: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
bc10: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
bc20: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
bc30: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
bc40: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
bc50: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
bc60: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
bc70: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
bc80: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bc90: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
bca0: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
bcb0: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
bcc0: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
bcd0: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
bce0: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
bcf0: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
bd00: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
bd10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bd20: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
bd30: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
bd40: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
bd50: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
bd60: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
bd70: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
bd80: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
bd90: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
bda0: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
bdb0: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
bdc0: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
bdd0: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
bde0: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
bdf0: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
be00: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
be10: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
be20: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
be30: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
be40: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
be50: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
be60: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
be70: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
be80: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
be90: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
bea0: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
beb0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
bec0: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
bed0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
bee0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
bef0: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
bf00: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
bf10: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
bf20: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
bf30: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
bf40: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
bf50: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
bf60: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
bf70: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
bf80: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
bf90: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
bfa0: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
bfb0: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
bfc0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
bfd0: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
bfe0: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
bff0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
c000: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
c010: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
c020: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
c030: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
c040: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
c050: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
c060: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
c070: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
c080: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
c090: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
c0a0: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
c0b0: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
c0c0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
c0d0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
c0e0: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
c0f0: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
c100: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
c110: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
c120: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
c130: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
c140: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
c150: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
c160: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
c170: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
c180: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
c190: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
c1a0: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
c1b0: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
c1c0: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
c1d0: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
c1e0: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
c1f0: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
c200: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
c210: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
c220: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c230: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
c240: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
c250: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
c260: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
c270: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
c280: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
c290: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
c2a0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c2b0: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
c2c0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
c2d0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
c2e0: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
c2f0: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
c300: 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
c310: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
c320: 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
c330: 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
c340: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
c350: 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
c360: 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
c370: 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
c380: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
c390: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
c3a0: 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
c3b0: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
c3c0: 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
c3d0: 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
c3e0: 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
c3f0: 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
c400: 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
c410: 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
c420: 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
c430: 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
c440: 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
c450: 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
c460: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
c470: 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
c480: 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
c490: 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
c4a0: 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
c4b0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
c4c0: 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
c4d0: 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
c4e0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
c4f0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
c500: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
c510: 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
c520: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
c530: 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
c540: 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
c550: 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
c560: 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
c570: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c580: 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
c590: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
c5a0: 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
c5b0: 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
c5c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
c5d0: 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
c5e0: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
c5f0: 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
c600: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
c610: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
c620: 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
c630: 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
c640: 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
c650: 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
c660: 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
c670: 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
c680: 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
c690: 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
c6a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
c6b0: 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
c6c0: 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
c6d0: 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
c6e0: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
c6f0: 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
c700: 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
c710: 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
c720: 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
c730: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
c740: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
c750: 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
c760: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
c770: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
c780: 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74  terface is not t
c790: 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20  hreadsafe.  The 
c7a0: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
c7b0: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
c7c0: 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
c7d0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
c7e0: 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
c7f0: 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
c800: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
c810: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46  ) is running.  F
c820: 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69  urthermore, sqli
c830: 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20  te3_config().** 
c840: 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
c850: 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
c860: 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
c870: 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
c880: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c890: 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
c8a0: 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
c8b0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
c8c0: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
c8d0: 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
c8e0: 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
c8f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
c900: 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
c910: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
c920: 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
c930: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
c940: 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
c950: 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
c960: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
c970: 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
c980: 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
c990: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
c9a0: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
c9b0: 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
c9c0: 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
c9d0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
c9e0: 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
c9f0: 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
ca00: 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  teger.** [SQLITE
ca10: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
ca20: 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72 61  READ | configura
ca30: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
ca40: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
ca50: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
ca60: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
ca70: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
ca80: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
ca90: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
caa0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51 4c  ding on the [SQL
cab0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
cac0: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67  ETHREAD | config
cad0: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
cae0: 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
caf0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
cb00: 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
cb10: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
cb20: 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
cb30: 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
cb40: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
cb50: 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
cb60: 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
cb70: 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
cb80: 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
cb90: 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
cba0: 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
cbb0: 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
cbc0: 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
cbd0: 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
cbe0: 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
cbf0: 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
cc00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
cc10: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ions.**.** The s
cc20: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
cc30: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
cc40: 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
cc50: 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
cc60: 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
cc70: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
cc80: 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
cc90: 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
cca0: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
ccb0: 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
ccc0: 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
ccd0: 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
cce0: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
ccf0: 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
cd00: 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
cd10: 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
cd20: 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
cd30: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
cd40: 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
cd50: 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
cd60: 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
cd70: 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
cd80: 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
cd90: 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
cda0: 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
cdb0: 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
cdc0: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
cdd0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
cde0: 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
cdf0: 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
ce00: 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
ce10: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
ce20: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
ce30: 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
ce40: 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
ce50: 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
ce60: 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
ce70: 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
ce80: 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
ce90: 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
cea0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f  .int sqlite3_db_
ceb0: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
cec0: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
ced0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
cee0: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
cef0: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
cf00: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
cf10: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
cf20: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
cf30: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
cf40: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
cf50: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
cf60: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
cf70: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
cf80: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
cf90: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
cfa0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
cfb0: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
cfc0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
cfd0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
cfe0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
cff0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
d000: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
d010: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
d020: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
d030: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
d040: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
d050: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
d060: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
d070: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
d080: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
d090: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
d0a0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
d0b0: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
d0c0: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
d0d0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
d0e0: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
d0f0: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
d100: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
d110: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
d120: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
d130: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
d140: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
d150: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
d160: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
d170: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
d180: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
d190: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
d1a0: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
d1b0: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
d1c0: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
d1d0: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
d1e0: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
d1f0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
d200: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
d210: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
d220: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
d230: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
d240: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
d250: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
d260: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
d270: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
d280: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
d290: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
d2a0: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
d2b0: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
d2c0: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
d2d0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
d2e0: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
d2f0: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
d300: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
d310: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
d320: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
d330: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
d340: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
d350: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
d360: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
d370: 6c 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20 6d  lloc and xFree m
d380: 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
d390: 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
d3a0: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
d3b0: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
d3c0: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
d3d0: 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20 78  ibrary..** The x
d3e0: 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20 6d  Realloc method m
d3f0: 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72 65  ust work like re
d400: 61 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68 65  alloc() from the
d410: 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
d420: 61 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ary.** with the 
d430: 65 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 69  exception that i
d440: 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
d450: 75 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c 6f  ument to xReallo
d460: 63 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78 52  c is zero,.** xR
d470: 65 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20 61  ealloc must be a
d480: 20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73 74   no-op - it must
d490: 20 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e 79   not perform any
d4a0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a 2a   allocation or.*
d4b0: 2a 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20  * deallocation. 
d4c0: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
d4d0: 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
d4e0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
d4f0: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
d500: 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
d510: 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
d520: 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
d530: 75 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69 6e  up..** And so in
d540: 20 63 61 73 65 73 20 77 68 65 72 65 20 78 52 6f   cases where xRo
d550: 75 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65 74  undup always ret
d560: 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20  urns a positive 
d570: 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61 6c  number,.** xReal
d580: 6c 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d 20  loc can perform 
d590: 65 78 61 63 74 6c 79 20 61 73 20 74 68 65 20 73  exactly as the s
d5a0: 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 20  tandard library 
d5b0: 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a 2a  realloc() and.**
d5c0: 20 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f 6d   still be in com
d5d0: 70 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68 69  pliance with thi
d5e0: 73 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 2e  s specification.
d5f0: 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
d600: 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
d610: 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
d620: 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
d630: 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
d640: 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
d650: 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
d660: 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
d670: 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
d680: 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
d690: 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
d6a0: 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
d6b0: 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
d6c0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
d6d0: 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
d6e0: 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
d6f0: 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
d700: 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
d710: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
d720: 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
d730: 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
d740: 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
d750: 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
d760: 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
d770: 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
d780: 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
d790: 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
d7a0: 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
d7b0: 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
d7c0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
d7d0: 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
d7e0: 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
d7f0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
d800: 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
d810: 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
d820: 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
d830: 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
d840: 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
d850: 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
d860: 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
d870: 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
d880: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
d890: 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
d8a0: 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
d8b0: 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
d8c0: 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
d8d0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
d8e0: 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61  cator.  (For exa
d8f0: 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
d900: 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
d910: 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
d920: 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
d930: 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
d940: 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
d950: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
d960: 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
d970: 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
d980: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
d990: 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
d9a0: 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
d9b0: 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
d9c0: 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
d9d0: 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
d9e0: 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
d9f0: 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
da00: 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
da10: 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
da20: 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
da30: 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
da40: 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
da50: 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
da60: 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
da70: 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
da80: 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
da90: 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
daa0: 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
dab0: 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
dac0: 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
dad0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
dae0: 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
daf0: 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
db00: 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
db10: 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
db20: 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
db30: 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
db40: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
db50: 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
db60: 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
db70: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
db80: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
db90: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
dba0: 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
dbb0: 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
dbc0: 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
dbd0: 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
dbe0: 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
dbf0: 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
dc00: 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
dc10: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
dc20: 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
dc30: 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
dc40: 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
dc50: 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
dc60: 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
dc70: 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
dc80: 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
dc90: 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
dca0: 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
dcb0: 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
dcc0: 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
dcd0: 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
dce0: 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
dcf0: 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
dd00: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
dd10: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
dd20: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
dd30: 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
dd40: 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
dd50: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
dd60: 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
dd70: 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
dd80: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
dd90: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
dda0: 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
ddb0: 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
ddc0: 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
ddd0: 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
dde0: 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
ddf0: 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
de00: 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
de10: 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
de20: 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
de30: 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
de40: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
de50: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
de60: 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
de70: 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
de80: 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
de90: 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
dea0: 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
deb0: 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
dec0: 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
ded0: 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
dee0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
def0: 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
df00: 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
df10: 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
df20: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
df30: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
df40: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
df50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
df60: 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
df70: 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
df80: 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
df90: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
dfa0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
dfb0: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
dfc0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
dfd0: 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
dfe0: 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
dff0: 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
e000: 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
e010: 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67  as the first arg
e020: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71  ument to the [sq
e030: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
e040: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
e050: 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
e060: 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
e070: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
e080: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
e090: 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
e0a0: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
e0b0: 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
e0c0: 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
e0d0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
e0e0: 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
e0f0: 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
e100: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  m [sqlite3_confi
e110: 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
e120: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
e130: 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20  ll worked.  The 
e140: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e150: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
e160: 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
e170: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
e180: 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
e190: 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
e1a0: 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
e1b0: 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
e1c0: 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
e1d0: 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
e1e0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
e1f0: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
e200: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
e210: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
e220: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
e230: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
e240: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
e250: 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
e260: 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
e270: 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
e280: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
e290: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
e2a0: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
e2b0: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
e2c0: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
e2d0: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
e2e0: 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
e2f0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
e300: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
e310: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
e320: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
e330: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
e340: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
e350: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
e360: 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
e370: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
e380: 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
e390: 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
e3a0: 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
e3b0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e3c0: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
e3d0: 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
e3e0: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
e3f0: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
e400: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
e410: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
e420: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
e430: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
e440: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
e450: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
e460: 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
e470: 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
e480: 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
e490: 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
e4a0: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
e4b0: 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
e4c0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
e4d0: 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
e4e0: 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
e4f0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e500: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
e510: 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
e520: 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
e530: 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
e540: 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
e550: 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
e560: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
e570: 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
e580: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
e590: 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
e5a0: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
e5b0: 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
e5c0: 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
e5d0: 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
e5e0: 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
e5f0: 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
e600: 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
e610: 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
e620: 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
e630: 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
e640: 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
e650: 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
e660: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
e670: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
e680: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
e690: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
e6a0: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
e6b0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
e6c0: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
e6d0: 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
e6e0: 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
e6f0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e700: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
e710: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
e720: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
e730: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
e740: 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
e750: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
e760: 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
e770: 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
e780: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
e790: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
e7a0: 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
e7b0: 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
e7c0: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
e7d0: 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
e7e0: 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
e7f0: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
e800: 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
e810: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
e820: 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
e830: 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
e840: 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
e850: 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
e860: 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
e870: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
e880: 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
e890: 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
e8a0: 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
e8b0: 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
e8c0: 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
e8d0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
e8e0: 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
e8f0: 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
e900: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
e910: 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
e920: 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
e930: 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
e940: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
e950: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
e960: 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
e970: 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
e980: 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
e990: 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
e9a0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
e9b0: 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
e9c0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
e9d0: 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
e9e0: 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
e9f0: 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
ea00: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
ea10: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
ea20: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
ea30: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
ea40: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
ea50: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
ea60: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
ea70: 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
ea80: 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
ea90: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
eaa0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
eab0: 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
eac0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
ead0: 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
eae0: 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
eaf0: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
eb00: 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
eb10: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
eb20: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
eb30: 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
eb40: 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
eb50: 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
eb60: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
eb70: 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
eb80: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
eb90: 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
eba0: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
ebb0: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
ebc0: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
ebd0: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
ebe0: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
ebf0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ec00: 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
ec10: 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
ec20: 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
ec30: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
ec40: 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
ec50: 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d  ite.)^ ^SQLite m
ec60: 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20  akes.** its own 
ec70: 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
ec80: 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
ec90: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
eca0: 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
ecb0: 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  re.** before the
ecc0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ecd0: 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
ece0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ecf0: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
ed00: 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
ed10: 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
ed20: 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
ed30: 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
ed40: 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
ed50: 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
ed60: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
ed70: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
ed80: 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
ed90: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
eda0: 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
edb0: 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
edc0: 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
edd0: 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
ede0: 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
edf0: 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
ee00: 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
ee10: 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
ee20: 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
ee30: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
ee40: 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
ee50: 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
ee60: 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
ee70: 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
ee80: 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
ee90: 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
eea0: 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
eeb0: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
eec0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
eed0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
eee0: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
eef0: 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
ef00: 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
ef10: 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
ef20: 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
ef30: 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
ef40: 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
ef50: 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
ef60: 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
ef70: 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
ef80: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
ef90: 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
efa0: 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a  disabled, the .*
efb0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
efc0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
efd0: 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
efe0: 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
eff0: 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
f000: 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
f010: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
f020: 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
f030: 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
f040: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
f050: 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
f060: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
f070: 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
f080: 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
f090: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f0a0: 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
f0b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
f0c0: 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
f0d0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
f0e0: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
f0f0: 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
f100: 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
f110: 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
f120: 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
f130: 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
f140: 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
f150: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
f160: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
f170: 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
f180: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
f190: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
f1a0: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
f1b0: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
f1c0: 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
f1d0: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
f1e0: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
f1f0: 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  ts:  A pointer a
f200: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
f210: 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
f220: 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
f230: 20 73 63 72 61 63 68 20 61 6c 6c 6f 63 61 74 69   scrach allocati
f240: 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
f250: 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
f260: 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
f270: 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
f280: 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
f290: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
f2a0: 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
f2b0: 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
f2c0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
f2d0: 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
f2e0: 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  16..** The first
f2f0: 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
f300: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
f310: 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
f320: 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74   buffer.** of at
f330: 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
f340: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
f350: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
f360: 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77   no more than tw
f370: 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  o scratch buffer
f380: 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53  s per thread.  S
f390: 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65  o.** N should be
f3a0: 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68   set to twice th
f3b0: 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d  e expected maxim
f3c0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  um number of thr
f3d0: 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  eads..** ^SQLite
f3e0: 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
f3f0: 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75  ire a scratch bu
f400: 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
f410: 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
f420: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
f430: 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51  age size. ^If SQ
f440: 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
f450: 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
f460: 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
f470: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
f480: 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
f490: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f4a0: 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
f4b0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
f4c0: 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
f4d0: 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
f4e0: 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a  y needed.</dd>.*
f4f0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
f500: 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
f510: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
f520: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
f530: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
f540: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
f550: 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
f560: 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
f570: 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
f580: 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
f590: 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
f5a0: 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  menation.  .** T
f5b0: 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
f5c0: 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
f5d0: 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
f5e0: 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
f5f0: 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
f600: 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
f610: 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  aded using the S
f620: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
f630: 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  CHE option..** T
f640: 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
f650: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
f660: 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
f670: 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69  er to 8-byte ali
f680: 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
f690: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
f6a0: 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
f6b0: 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
f6c0: 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
f6d0: 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
f6e0: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
f6f0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
f700: 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
f710: 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
f720: 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
f730: 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75  2 and 32768) plu
f740: 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61  s a little extra
f750: 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
f760: 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
f770: 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65  page header size
f780: 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74   is 20 to 40 byt
f790: 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a  es depending on.
f7a0: 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68  ** the host arch
f7b0: 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69  itecture.  ^It i
f7c0: 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
f7d0: 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
f7e0: 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20  d memory,.** to 
f7f0: 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65  make sz a little
f800: 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65   too large.  The
f810: 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
f820: 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
f830: 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
f840: 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
f850: 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
f860: 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
f870: 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
f880: 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
f890: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f8a0: 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
f8b0: 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
f8c0: 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
f8d0: 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
f8e0: 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
f8f0: 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
f900: 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
f910: 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
f920: 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
f930: 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
f940: 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
f950: 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
f960: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
f970: 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
f980: 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
f990: 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  ** The pointer i
f9a0: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
f9b0: 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
f9c0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
f9d0: 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
f9e0: 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
f9f0: 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
fa00: 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
fa10: 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
fa20: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
fa30: 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
fa40: 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
fa50: 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
fa60: 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
fa70: 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
fa80: 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
fa90: 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
faa0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
fab0: 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
fac0: 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
fad0: 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
fae0: 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
faf0: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
fb00: 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
fb10: 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
fb20: 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
fb30: 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
fb40: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
fb50: 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
fb60: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
fb70: 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
fb80: 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
fb90: 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
fba0: 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
fbb0: 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
fbc0: 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
fbd0: 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
fbe0: 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
fbf0: 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
fc00: 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
fc10: 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
fc20: 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
fc30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
fc40: 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
fc50: 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
fc60: 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
fc70: 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
fc80: 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
fc90: 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
fca0: 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
fcb0: 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
fcc0: 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
fcd0: 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
fce0: 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
fcf0: 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
fd00: 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
fd10: 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
fd20: 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
fd30: 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
fd40: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
fd50: 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
fd60: 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
fd70: 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
fd80: 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
fd90: 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
fda0: 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
fdb0: 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
fdc0: 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
fdd0: 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
fde0: 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
fdf0: 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
fe00: 70 70 65 64 20 61 74 20 32 5e 31 32 2e 20 52 65  pped at 2^12. Re
fe10: 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
fe20: 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
fe30: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
fe40: 7a 65 20 61 72 65 20 32 5e 35 20 74 68 72 6f 75  ze are 2^5 throu
fe50: 67 68 20 32 5e 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  gh 2^8.</dd>.**.
fe60: 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
fe70: 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
fe80: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
fe90: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
fea0: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
feb0: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
fec0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
fed0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
fee0: 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
fef0: 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
ff00: 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
ff10: 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
ff20: 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
ff30: 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
ff40: 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
ff50: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
ff60: 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
ff70: 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
ff80: 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
ff90: 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
ffa0: 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
ffb0: 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
ffc0: 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
ffd0: 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
ffe0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
fff0: 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
10000 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
10010 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
10020 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
10030 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
10040 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
10050 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
10060 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
10070 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
10080 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
10090 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
100a0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
100b0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
100c0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
100d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
100e0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
100f0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
10100 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
10110 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
10120 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
10130 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c  CONFIG_GETMUTEX<
10140 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
10150 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
10160 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
10170 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
10180 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
10190 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
101a0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
101b0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
101c0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
101d0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
101e0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
101f0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
10200 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
10210 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
10220 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
10230 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
10240 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
10250 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
10260 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
10270 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
10280 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
10290 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
102a0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
102b0 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
102c0 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
102d0 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
102e0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
102f0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
10300 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
10310 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
10320 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
10330 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
10340 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
10350 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
10360 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
10370 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
10380 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
10390 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
103a0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
103b0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
103c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
103d0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
103e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
103f0 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
10400 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10410 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
10420 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
10430 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
10440 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
10450 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65  determine the de
10460 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20  fault.** memory 
10470 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74  allocation for t
10480 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
10490 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e  ory allocator on
104a0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
104b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
104c0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
104d0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
104e0 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
104f0 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
10500 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
10510 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
10520 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
10530 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
10540 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
10550 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  )^  ^(This optio
10560 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69  n sets the.** <i
10570 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
10580 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
10590 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
105a0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
105b0 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33  verb to [sqlite3
105c0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
105d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
105e0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
105f0 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
10600 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
10610 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
10620 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
10630 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
10640 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
10650 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10660 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
10670 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
10680 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a   a pointer to.**
10690 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
106a0 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
106b0 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
106c0 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
106d0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
106e0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
106f0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
10700 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
10710 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
10720 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
10730 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
10740 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
10750 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
10760 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
10770 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
10780 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
10790 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
107a0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
107b0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
107c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
107d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
107e0 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  e_methods] objec
107f0 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
10800 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  s of the current
10810 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69  .** page cache i
10820 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
10830 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
10840 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ^ </dd>.**.** <d
10850 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10860 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
10870 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
10880 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
10890 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
108a0 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
108b0 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
108c0 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
108d0 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
108e0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
108f0 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
10900 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
10910 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
10920 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
10930 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
10940 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
10950 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
10960 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
10970 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
10980 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
10990 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
109a0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
109b0 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
109c0 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
109d0 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
109e0 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
109f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
10a00 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
10a10 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
10a20 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
10a30 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
10a40 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
10a50 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
10a60 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
10a70 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
10a80 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
10a90 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
10aa0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
10ab0 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
10ac0 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
10ad0 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
10ae0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
10af0 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
10b00 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
10b10 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
10b20 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
10b30 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
10b40 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
10b50 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
10b60 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
10b70 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
10b80 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
10b90 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
10ba0 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
10bb0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
10bc0 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
10bd0 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
10be0 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
10bf0 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
10c00 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
10c10 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
10c20 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
10c30 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
10c40 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
10c50 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
10c60 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
10c70 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10c80 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
10c90 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
10ca0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
10cb0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
10cc0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
10cd0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
10ce0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
10cf0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
10d00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
10d10 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
10d20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
10d30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
10d40 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
10d50 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
10d60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
10d70 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
10d80 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
10d90 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
10da0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10db0 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
10dc0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
10dd0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
10de0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10df0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
10e00 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
10e10 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
10e20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
10e30 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
10e40 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
10e50 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
10e60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10e70 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
10e80 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
10e90 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
10ea0 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
10eb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
10ec0 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
10ed0 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
10ee0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10ef0 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
10f00 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
10f10 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
10f20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10f30 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
10f40 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
10f50 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
10f60 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
10f70 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
10f80 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
10f90 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
10fa0 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
10fb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
10fc0 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
10fd0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
10fe0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10ff0 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
11000 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  4  /* sqlite3_pc
11010 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
11020 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11030 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
11040 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74      15  /* sqlit
11050 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
11060 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
11070 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
11080 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
11090 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
110a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
110b0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
110c0 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
110d0 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
110e0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
110f0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
11100 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
11110 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11120 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
11130 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
11140 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11150 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
11160 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
11170 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
11180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11190 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
111a0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
111b0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
111c0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
111d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
111e0 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
111f0 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
11200 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
11210 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
11220 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
11230 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
11240 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
11250 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
11260 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
11270 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11280 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
11290 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
112a0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
112b0 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
112c0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
112d0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
112e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
112f0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
11300 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
11310 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
11320 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
11330 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
11340 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
11350 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
11360 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
11370 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
11380 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
11390 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
113a0 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
113b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
113c0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
113d0 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
113e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
113f0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
11400 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
11410 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6d 65  pointer to an me
11420 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
11430 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
11440 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
11450 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11460 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
11470 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
11480 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
11490 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
114a0 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
114b0 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
114c0 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
114d0 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
114e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
114f0 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
11500 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
11510 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
11520 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
11530 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
11540 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
11550 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
11560 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
11570 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
11580 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
11590 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
115a0 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
115b0 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
115c0 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
115d0 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
115e0 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
115f0 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
11600 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
11610 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
11620 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
11630 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
11640 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
11650 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
11660 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
11670 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
11680 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
11690 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
116a0 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
116b0 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
116c0 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
116d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
116e0 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
116f0 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
11700 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
11710 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
11720 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
11730 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
11740 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
11750 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
11760 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
11770 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
11780 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
11790 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
117a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
117b0 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
117c0 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
117d0 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
117e0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
117f0 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
11800 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
11810 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
11820 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
11830 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
11840 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
11850 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
11860 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
11870 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
11880 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
11890 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
118a0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
118b0 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
118c0 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
118d0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
118e0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
118f0 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
11900 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
11910 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
11920 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
11930 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
11940 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
11950 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
11960 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
11970 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
11980 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
11990 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
119a0 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
119b0 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
119c0 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
119d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
119e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
119f0 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
11a00 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
11a10 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
11a20 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
11a30 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
11a40 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
11a50 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
11a60 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
11a70 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
11a80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
11a90 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
11aa0 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
11ab0 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
11ac0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
11ad0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
11ae0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
11af0 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
11b00 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
11b10 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
11b20 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
11b30 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
11b40 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
11b50 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
11b60 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
11b70 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
11b80 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
11b90 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
11ba0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
11bb0 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
11bc0 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
11bd0 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 65 72  to enable triger
11be0 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
11bf0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
11c00 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
11c10 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
11c20 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
11c30 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
11c40 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
11c50 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
11c60 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
11c70 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
11c80 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
11c90 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
11ca0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
11cb0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
11cc0 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
11cd0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
11ce0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
11cf0 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
11d00 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
11d10 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
11d20 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
11d30 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
11d40 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
11d50 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
11d60 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
11d70 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
11d80 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
11d90 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e       1002  /* in
11da0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
11db0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
11dc0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
11dd0 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69    1003  /* int i
11de0 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
11df0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
11e00 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
11e10 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
11e20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
11e30 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
11e40 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
11e50 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
11e60 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
11e70 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
11e80 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
11e90 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
11ea0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
11eb0 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
11ec0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
11ed0 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
11ee0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
11ef0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
11f00 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
11f10 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
11f20 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
11f30 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
11f40 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
11f50 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
11f60 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
11f70 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
11f80 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
11f90 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
11fa0 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
11fb0 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
11fc0 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
11fd0 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
11fe0 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
11ff0 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
12000 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
12010 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
12020 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
12030 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
12040 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
12050 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
12060 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
12070 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
12080 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
12090 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
120a0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
120b0 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
120c0 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
120d0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
120e0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
120f0 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  id] of the most 
12100 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73  recent.** succes
12110 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
12120 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
12130 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61  from the [databa
12140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
12150 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
12160 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f  rgument.  ^If no
12170 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
12180 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76  ERT]s.** have ev
12190 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
121a0 68 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e  hat database con
121b0 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73  nection, zero is
121c0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
121d0 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
121e0 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
121f0 61 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20  a trigger, then 
12200 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
12210 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
12220 6f 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62  ow is returned b
12230 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61  y this routine a
12240 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
12250 69 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67  igger is running
12260 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
12270 65 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e  e trigger termin
12280 61 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ates, the value 
12290 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
122a0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65   routine.** reve
122b0 72 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20  rts to the last 
122c0 76 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62  value inserted b
122d0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
122e0 72 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  r fired.)^.**.**
122f0 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
12300 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
12310 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
12320 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
12330 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
12340 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
12350 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
12360 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
12370 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
12380 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
12390 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
123a0 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
123b0 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
123c0 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
123d0 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
123e0 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
123f0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
12400 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
12410 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
12420 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
12430 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
12440 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
12450 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
12460 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
12470 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
12480 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
12490 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
124a0 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
124b0 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
124c0 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
124d0 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
124e0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
124f0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
12500 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
12510 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
12520 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
12530 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
12540 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
12550 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
12560 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
12570 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
12580 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
12590 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
125a0 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
125b0 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
125c0 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
125d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
125e0 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
125f0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
12600 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
12610 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
12620 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
12630 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
12640 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
12650 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
12660 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
12670 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
12680 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
12690 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
126a0 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
126b0 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
126c0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
126d0 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
126e0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
126f0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
12700 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
12710 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
12720 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
12730 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
12740 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
12750 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
12760 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
12770 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
12780 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
12790 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
127a0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
127b0 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
127c0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
127d0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
127e0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
127f0 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
12800 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
12810 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
12820 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
12830 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
12840 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
12850 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
12860 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
12870 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
12880 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
12890 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
128a0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
128b0 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
128c0 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
128d0 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
128e0 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
128f0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
12900 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
12910 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
12920 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
12930 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
12940 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
12950 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
12960 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
12970 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
12980 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
12990 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
129a0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
129b0 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
129c0 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
129d0 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
129e0 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
129f0 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
12a00 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
12a10 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
12a20 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
12a30 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
12a40 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
12a50 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
12a60 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
12a70 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
12a80 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
12a90 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
12aa0 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
12ab0 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
12ac0 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
12ad0 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
12ae0 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
12af0 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
12b00 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
12b10 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
12b20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
12b30 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
12b40 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
12b50 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
12b60 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
12b70 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
12b80 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
12b90 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
12ba0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
12bb0 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
12bc0 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
12bd0 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
12be0 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
12bf0 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
12c00 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
12c10 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
12c20 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
12c30 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
12c40 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
12c50 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
12c60 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
12c70 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
12c80 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
12c90 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
12ca0 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
12cb0 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
12cc0 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
12cd0 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
12ce0 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
12cf0 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
12d00 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
12d10 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
12d20 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
12d30 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
12d40 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
12d50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
12d60 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
12d70 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
12d80 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
12d90 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
12da0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
12db0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
12dc0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
12dd0 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
12de0 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
12df0 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
12e00 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
12e10 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
12e20 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
12e30 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
12e40 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
12e50 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
12e60 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
12e70 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
12e80 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
12e90 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
12ea0 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
12eb0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
12ec0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
12ed0 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
12ee0 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
12ef0 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
12f00 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
12f10 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
12f20 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
12f30 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
12f40 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
12f50 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
12f60 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
12f70 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
12f80 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
12f90 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
12fa0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
12fb0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
12fc0 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
12fd0 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
12fe0 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
12ff0 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
13000 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
13010 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
13020 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
13030 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
13040 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
13050 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
13060 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
13070 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
13080 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
13090 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
130a0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
130b0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
130c0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
130d0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
130e0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
130f0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
13100 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13110 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
13120 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
13130 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
13140 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
13150 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
13160 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
13170 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
13180 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
13190 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
131a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
131b0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
131c0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
131d0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
131e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
131f0 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
13200 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e  es caused by [IN
13210 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54  SERT],.** [UPDAT
13220 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
13230 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
13240 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
13250 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
13260 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63  ened..** ^(The c
13270 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
13280 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
13290 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65  hanges() include
132a0 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a  s all changes.**
132b0 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54   from all [CREAT
132c0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
132d0 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e  ger] contexts an
132e0 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62  d changes made b
132f0 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  y.** [foreign ke
13300 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65  y actions]. Howe
13310 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
13320 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
13330 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
13340 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
13350 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
13360 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
13370 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
13380 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
13390 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
133a0 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
133b0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
133c0 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
133d0 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
133e0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
133f0 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
13400 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
13410 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
13420 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
13430 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
13440 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
13450 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .)^.** ^The sqli
13460 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
13470 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  s() function cou
13480 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20  nts the changes 
13490 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68  as soon as.** th
134a0 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
134b0 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
134c0 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
134d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
134e0 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64  dle.** is passed
134f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
13500 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
13510 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
13520 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
13530 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
13540 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
13550 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
13560 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
13570 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
13580 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
13590 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
135a0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
135b0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
135c0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
135d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
135e0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
135f0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
13600 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
13610 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
13620 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
13630 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
13640 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
13650 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
13660 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
13670 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
13680 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
13690 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
136a0 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
136b0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
136c0 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
136d0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
136e0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
136f0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
13700 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
13710 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
13720 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
13730 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
13740 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
13750 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
13760 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
13770 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
13780 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
13790 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
137a0 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
137b0 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
137c0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
137d0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
137e0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
137f0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
13800 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
13810 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
13820 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
13830 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
13840 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
13850 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
13860 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
13870 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
13880 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13890 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
138a0 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
138b0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
138c0 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
138d0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
138e0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
138f0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
13900 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
13910 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
13920 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
13930 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
13940 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
13950 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
13960 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
13970 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
13980 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
13990 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
139a0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
139b0 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
139c0 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
139d0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
139e0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
139f0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
13a00 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
13a10 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
13a20 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
13a30 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
13a40 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
13a50 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
13a60 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
13a70 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
13a80 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
13a90 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
13aa0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
13ab0 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
13ac0 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
13ad0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
13ae0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
13af0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
13b00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
13b10 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
13b20 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
13b30 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
13b40 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
13b50 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
13b60 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
13b70 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
13b80 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
13b90 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
13ba0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
13bb0 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
13bc0 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
13bd0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
13be0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
13bf0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
13c00 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
13c10 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
13c20 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
13c30 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
13c40 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
13c50 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
13c60 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
13c70 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
13c80 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
13c90 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
13ca0 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
13cb0 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
13cc0 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
13cd0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
13ce0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
13cf0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
13d00 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
13d10 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
13d20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
13d30 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
13d40 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
13d50 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
13d60 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
13d70 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
13d80 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
13d90 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
13da0 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
13db0 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
13dc0 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
13dd0 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
13de0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13df0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
13e00 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
13e10 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
13e20 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
13e30 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
13e40 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
13e50 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
13e60 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
13e70 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
13e80 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
13e90 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
13ea0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
13eb0 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
13ec0 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
13ed0 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
13ee0 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
13ef0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
13f00 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
13f10 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
13f20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
13f30 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
13f40 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
13f50 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
13f60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
13f70 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
13f80 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
13f90 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
13fa0 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
13fb0 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
13fc0 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
13fd0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
13fe0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
13ff0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
14000 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
14010 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
14020 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
14030 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
14040 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
14050 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
14060 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
14070 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
14080 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
14090 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
140a0 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
140b0 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
140c0 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
140d0 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
140e0 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
140f0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
14100 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
14110 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
14120 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
14130 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
14140 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
14150 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
14160 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
14170 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
14180 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
14190 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
141a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
141b0 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
141c0 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
141d0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
141e0 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
141f0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
14200 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
14210 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
14220 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
14230 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
14240 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
14250 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
14260 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
14270 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
14280 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
14290 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
142a0 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
142b0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
142c0 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
142d0 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
142e0 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
142f0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
14300 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
14310 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
14320 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
14330 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
14340 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
14350 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
14360 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
14370 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
14380 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
14390 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
143a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
143b0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
143c0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
143d0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
143e0 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
143f0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
14400 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
14410 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
14420 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
14430 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
14440 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
14450 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
14460 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
14470 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
14480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
14490 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
144a0 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
144b0 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
144c0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
144d0 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
144e0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ck function that
144f0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
14500 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  d whenever.** an
14510 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
14520 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62   to open a datab
14530 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61  ase table that a
14540 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a  nother thread.**
14550 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20   or process has 
14560 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  locked..**.** ^I
14570 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
14580 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
14590 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
145a0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
145b0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
145c0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
145d0 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
145e0 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
145f0 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
14600 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
14610 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
14620 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
14630 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
14640 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
14650 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
14660 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
14670 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
14680 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
14690 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
146a0 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
146b0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
146c0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
146d0 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
146e0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
146f0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
14700 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
14710 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
14720 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
14730 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
14740 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
14750 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76   this locking ev
14760 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
14770 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
14780 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
14790 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
147a0 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
147b0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
147c0 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
147d0 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
147e0 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
147f0 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64  KED] is returned
14800 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
14810 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
14820 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f  n-zero, then ano
14830 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20  ther attempt.** 
14840 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
14850 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
14860 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65   reading and the
14870 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
14880 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
14890 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
148a0 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
148b0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
148c0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
148d0 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
148e0 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
148f0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
14900 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
14910 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
14920 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
14930 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
14940 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
14950 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
14960 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
14970 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
14980 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73  ERR_BLOCKED] ins
14990 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
149a0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
149b0 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
149c0 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
149d0 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
149e0 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
149f0 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
14a00 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
14a10 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
14a20 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
14a30 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
14a40 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
14a50 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
14a60 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
14a70 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
14a80 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
14a90 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
14aa0 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
14ab0 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
14ac0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
14ad0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
14ae0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
14af0 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
14b00 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
14b10 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
14b20 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
14b30 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
14b40 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
14b50 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
14b60 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
14b70 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
14b80 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
14b90 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
14ba0 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
14bb0 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
14bc0 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
14bd0 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
14be0 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
14bf0 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
14c00 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
14c10 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
14c20 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
14c30 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
14c40 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
14c50 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
14c60 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  The [SQLITE_BUSY
14c70 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65  ] error is conve
14c80 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f  rted to [SQLITE_
14c90 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a  IOERR_BLOCKED].*
14ca0 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
14cb0 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
14cc0 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61  f a large transa
14cd0 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20  ction where all 
14ce0 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77  the.** changes w
14cf0 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f  ill not fit into
14d00 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63   the in-memory c
14d10 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69  ache.  SQLite wi
14d20 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f  ll.** already ho
14d30 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f  ld a RESERVED lo
14d40 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ck on the databa
14d50 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20  se file, but it 
14d60 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d  needs.** to prom
14d70 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f  ote this lock to
14d80 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68   EXCLUSIVE so th
14d90 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20  at it can spill 
14da0 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69  cache.** pages i
14db0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
14dc0 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61   file without ha
14dd0 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74  rm to concurrent
14de0 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49  .** readers.  ^I
14df0 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  f it is unable t
14e00 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f  o promote the lo
14e10 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d  ck, then the in-
14e20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20  memory.** cache 
14e30 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20  will be left in 
14e40 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20  an inconsistent 
14e50 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65  state and so the
14e60 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69   error.** code i
14e70 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20  s promoted from 
14e80 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62  the relatively b
14e90 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55  enign [SQLITE_BU
14ea0 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f  SY] to.** the mo
14eb0 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54  re severe [SQLIT
14ec0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
14ed0 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63  .  ^This error c
14ee0 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a  ode promotion.**
14ef0 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d   forces an autom
14f00 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66  atic rollback of
14f10 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53   the changes.  S
14f20 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65  ee the.** <a hre
14f30 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69  f="/cvstrac/wiki
14f40 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c  ?p=CorruptionFol
14f50 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22  lowingBusyError"
14f60 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46  >.** CorruptionF
14f70 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f  ollowingBusyErro
14f80 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20  r</a> wiki page 
14f90 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e  for a discussion
14fa0 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20   of why.** this 
14fb0 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a  is important..**
14fc0 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
14fd0 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
14fe0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
14ff0 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
15000 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
15010 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
15020 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
15030 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
15040 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
15050 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
15060 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
15070 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
15080 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c  imeout()].** wil
15090 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c  l also set or cl
150a0 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e  ear the busy han
150b0 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dler..**.** The 
150c0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68  busy callback sh
150d0 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e  ould not take an
150e0 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20  y actions which 
150f0 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61  modify the.** da
15100 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15110 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
15120 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
15130 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
15140 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
15150 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
15160 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
15170 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
15180 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
15190 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
151a0 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
151b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
151c0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
151d0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e  y handler..*/.in
151e0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  t sqlite3_busy_h
151f0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
15200 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
15210 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
15220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
15230 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
15240 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
15250 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
15260 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
15270 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
15280 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
15290 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
152a0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
152b0 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
152c0 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
152d0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
152e0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
152f0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
15300 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
15310 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
15320 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
15330 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
15340 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
15350 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
15360 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
15370 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
15380 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
15390 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
153a0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
153b0 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
153c0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
153d0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
153e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74  this routine wit
153f0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65  h an argument le
15400 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
15410 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e   to zero.** turn
15420 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68  s off all busy h
15430 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  andlers..**.** ^
15440 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
15450 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
15460 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70   handler for a p
15470 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
15480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15490 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e  n] any any given
154a0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
154b0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
154c0 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
154d0 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
154e0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
154f0 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
15500 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
15510 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
15520 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
15530 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e  cleared.)^.*/.in
15540 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
15550 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
15560 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
15570 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
15580 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
15590 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
155a0 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ies.**.** This i
155b0 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
155c0 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
155d0 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
155e0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
155f0 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
15600 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
15610 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
15620 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
15630 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
15640 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
15650 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
15660 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
15670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
15680 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
15690 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
156a0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
156b0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
156c0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
156d0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
156e0 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
156f0 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
15700 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
15710 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
15720 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
15730 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
15740 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
15750 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
15760 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
15770 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
15780 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
15790 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
157a0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
157b0 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
157c0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
157d0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
157e0 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
157f0 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
15800 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
15810 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
15820 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
15830 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
15840 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
15850 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
15860 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
15870 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
15880 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
15890 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
158a0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
158b0 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
158c0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
158d0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
158e0 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
158f0 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
15900 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
15910 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
15920 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
15930 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
15940 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
15950 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
15960 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
15970 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
15980 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
15990 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
159a0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
159b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
159c0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
159d0 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
159e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
159f0 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
15a00 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
15a10 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
15a20 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
15a30 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
15a40 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
15a50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
15a60 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
15a70 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
15a80 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
15a90 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
15aa0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
15ab0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
15ac0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
15ad0 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
15ae0 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
15af0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
15b00 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
15b10 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
15b20 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
15b30 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
15b40 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
15b50 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
15b60 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
15b70 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
15b80 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
15b90 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
15ba0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
15bb0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
15bc0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
15bd0 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
15be0 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
15bf0 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
15c00 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
15c10 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
15c20 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
15c30 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
15c40 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
15c50 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
15c60 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
15c70 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
15c80 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
15c90 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
15ca0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
15cb0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
15cc0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
15cd0 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
15ce0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
15cf0 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
15d00 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
15d10 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
15d20 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
15d30 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
15d40 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
15d50 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
15d60 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
15d70 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
15d80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
15d90 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
15da0 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
15db0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
15dc0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
15dd0 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
15de0 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
15df0 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
15e00 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
15e10 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
15e20 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
15e30 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
15e40 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
15e50 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
15e60 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
15e70 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
15e80 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
15e90 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
15ea0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
15eb0 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
15ec0 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
15ed0 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
15ee0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
15ef0 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
15f00 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
15f10 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
15f20 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
15f30 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
15f40 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
15f50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
15f60 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
15f70 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
15f80 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
15f90 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
15fa0 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
15fb0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
15fc0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
15fd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
15fe0 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
15ff0 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
16000 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
16010 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
16020 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
16030 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
16040 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
16050 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
16060 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
16070 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
16080 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
16090 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
160a0 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
160b0 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
160c0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
160d0 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
160e0 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
160f0 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
16100 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
16110 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
16120 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
16130 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
16140 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
16150 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
16160 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
16170 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
16180 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
16190 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
161a0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
161b0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
161c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
161d0 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  rrmsg()]..*/.int
161e0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
161f0 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
16200 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
16210 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
16220 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
16230 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
16240 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
16250 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
16260 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
16270 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
16280 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
16290 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
162a0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
162b0 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
162c0 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
162d0 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
162e0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
162f0 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
16300 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
16310 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
16320 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
16330 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
16340 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
16350 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
16360 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
16370 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
16380 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
16390 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
163a0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
163b0 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
163c0 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
163d0 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
163e0 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
163f0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
16400 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
16410 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
16420 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
16430 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
16440 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
16450 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
16460 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
16470 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
16480 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
16490 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
164a0 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
164b0 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
164c0 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
164d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
164e0 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
164f0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
16500 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
16510 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
16520 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
16530 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
16540 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
16550 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
16560 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
16570 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
16580 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
16590 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
165a0 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
165b0 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
165c0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
165d0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
165e0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
165f0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
16600 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
16610 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
16620 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
16630 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
16640 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
16650 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
16660 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
16670 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
16680 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
16690 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
166a0 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
166b0 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
166c0 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
166d0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
166e0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
166f0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
16700 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
16710 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
16720 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
16730 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
16740 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
16750 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
16760 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
16770 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
16780 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
16790 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
167a0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
167b0 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
167c0 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
167d0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
167e0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
167f0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
16800 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
16810 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
16820 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
16830 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
16840 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
16850 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
16860 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
16870 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
16880 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
16890 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
168a0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
168b0 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
168c0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
168d0 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
168e0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
168f0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
16900 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
16910 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
16920 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
16930 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
16940 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
16950 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
16960 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
16970 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
16980 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
16990 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
169a0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
169b0 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
169c0 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
169d0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
169e0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
169f0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
16a00 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
16a10 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
16a20 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
16a30 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
16a40 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
16a50 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
16a60 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
16a70 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
16a80 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
16a90 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
16aa0 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
16ab0 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
16ac0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
16ad0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
16ae0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
16af0 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
16b00 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
16b10 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  l-terminated.** 
16b20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20  string from the 
16b30 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20  argument list.  
16b40 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62  But %q also doub
16b50 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63  les every '\'' c
16b60 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20  haracter..** %q 
16b70 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20  is designed for 
16b80 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72  use inside a str
16b90 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20  ing literal.)^  
16ba0 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68  By doubling each
16bb0 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74   '\''.** charact
16bc0 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68  er it escapes th
16bd0 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64  at character and
16be0 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65   allows it to be
16bf0 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a   inserted into.*
16c00 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a  * the string..**
16c10 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  .** For example,
16c20 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69   assume the stri
16c30 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78  ng variable zTex
16c40 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20  t contains text 
16c50 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
16c60 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
16c70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54  re>.**  char *zT
16c80 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61  ext = "It's a ha
16c90 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f  ppy day!";.** </
16ca0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
16cb0 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20  >.**.** One can 
16cc0 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e  use this text in
16cd0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
16ce0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
16cf0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
16d00 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
16d10 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
16d20 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
16d30 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
16d40 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b  ('%q')", zText);
16d50 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
16d60 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
16d70 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
16d80 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
16d90 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
16da0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75  ote>.**.** Becau
16db0 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74  se the %q format
16dc0 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c   string is used,
16dd0 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63   the '\'' charac
16de0 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20  ter in zText.** 
16df0 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74  is escaped and t
16e00 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64  he SQL generated
16e10 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
16e20 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
16e30 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
16e40 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
16e50 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68  ALUES('It''s a h
16e60 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c  appy day!').** <
16e70 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
16e80 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  e>.**.** This is
16e90 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77   correct.  Had w
16ea0 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61  e used %s instea
16eb0 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e  d of %q, the gen
16ec0 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f  erated SQL.** wo
16ed0 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20  uld have looked 
16ee0 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
16ef0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
16f00 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
16f10 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
16f20 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64  ('It's a happy d
16f30 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ay!');.** </pre>
16f40 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
16f50 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20  .** This second 
16f60 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51  example is an SQ
16f70 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20  L syntax error. 
16f80 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75   As a general ru
16f90 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a  le you should.**
16fa0 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69   always use %q i
16fb0 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65  nstead of %s whe
16fc0 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74  n inserting text
16fd0 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c   into a string l
16fe0 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  iteral..**.** ^(
16ff0 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f  The %Q option wo
17000 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65  rks like %q exce
17010 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20  pt it also adds 
17020 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72  single quotes ar
17030 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73  ound.** the outs
17040 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c  ide of the total
17050 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69   string.  Additi
17060 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70  onally, if the p
17070 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a  arameter in the.
17080 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  ** argument list
17090 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
170a0 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74  er, %Q substitut
170b0 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c  es the text "NUL
170c0 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73  L" (without.** s
170d0 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e  ingle quotes).)^
170e0 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c    So, for exampl
170f0 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79  e, one could say
17100 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
17110 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
17120 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
17130 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
17140 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
17150 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74  LUES(%Q)", zText
17160 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
17170 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
17180 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
17190 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
171a0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
171b0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
171c0 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c   code above will
171d0 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63   render a correc
171e0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
171f0 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76  in the zSQL.** v
17200 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20  ariable even if 
17210 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62  the zText variab
17220 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  le is a NULL poi
17230 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  nter..**.** ^(Th
17240 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
17250 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
17260 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
17270 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
17280 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
17290 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
172a0 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
172b0 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
172c0 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
172d0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
172e0 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
172f0 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a  ing.)^.*/.char *
17300 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
17310 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29  const char*,...)
17320 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
17330 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
17340 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
17350 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
17360 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
17370 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
17380 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
17390 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
173a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
173b0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
173c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
173d0 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
173e0 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
173f0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
17400 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
17410 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
17420 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
17430 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
17440 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
17450 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
17460 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
17470 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
17480 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
17490 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
174a0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
174b0 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
174c0 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
174d0 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
174e0 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
174f0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
17500 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
17510 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
17520 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
17530 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
17540 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
17550 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
17560 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
17570 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
17580 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
17590 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
175a0 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
175b0 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
175c0 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
175d0 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
175e0 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
175f0 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
17600 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
17610 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
17620 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
17630 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
17640 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
17650 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
17660 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
17670 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
17680 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
17690 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
176a0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
176b0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
176c0 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
176d0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
176e0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
176f0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
17700 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
17710 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
17720 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
17730 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
17740 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
17750 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
17760 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
17770 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
17780 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
17790 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
177a0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
177b0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
177c0 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
177d0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
177e0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
177f0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
17800 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
17810 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
17820 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
17830 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
17840 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
17850 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
17860 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
17870 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
17880 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
17890 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
178a0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
178b0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
178c0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
178d0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
178e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
178f0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
17900 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
17910 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
17920 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
17930 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
17940 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
17950 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
17960 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
17970 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17980 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
17990 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
179a0 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
179b0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
179c0 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72  .)^ ^ If the fir
179d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
179e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
179f0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
17a00 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
17a10 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
17a20 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
17a30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
17a40 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
17a50 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
17a60 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
17a70 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
17a80 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
17a90 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
17aa0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
17ab0 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
17ac0 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
17ad0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
17ae0 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
17af0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
17b00 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
17b10 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
17b20 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
17b30 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
17b40 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
17b50 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
17b60 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
17b70 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
17b80 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
17b90 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
17ba0 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
17bb0 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
17bc0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
17bd0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
17be0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
17bf0 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
17c00 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
17c10 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
17c20 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
17c30 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
17c40 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
17c50 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
17c60 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
17c70 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
17c80 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
17c90 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
17ca0 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
17cb0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
17cc0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
17cd0 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
17ce0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  d..**.** ^The me
17cf0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
17d00 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
17d10 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
17d20 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
17d30 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
17d40 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
17d50 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
17d60 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
17d70 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
17d80 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
17d90 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
17da0 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
17db0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
17dc0 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
17dd0 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
17de0 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
17df0 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
17e00 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
17e10 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
17e20 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
17e30 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
17e40 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
17e50 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
17e60 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
17e70 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
17e80 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
17e90 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
17ea0 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
17eb0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
17ec0 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
17ed0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f  .**.** The Windo
17ee0 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
17ef0 6c 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74  layer calls.** t
17f00 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
17f10 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
17f20 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
17f30 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
17f40 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
17f50 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
17f60 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
17f70 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
17f80 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
17f90 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
17fa0 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
17fb0 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
17fc0 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
17fd0 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65  ation errors are
17fe0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
17ff0 2a 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72  * they are repor
18000 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
18010 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
18020 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
18030 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
18040 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
18050 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
18060 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
18070 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
18080 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
18090 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
180a0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
180b0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
180c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
180d0 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
180e0 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
180f0 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
18100 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
18110 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
18120 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
18130 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
18140 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
18150 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
18160 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
18170 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
18180 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
18190 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
181a0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
181b0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
181c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
181d0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
181e0 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69  malloc(int);.voi
181f0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
18200 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
18210 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
18220 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
18230 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
18240 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
18250 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
18260 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
18270 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
18280 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
18290 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
182a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
182b0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
182c0 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
182d0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
182e0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
182f0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
18300 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
18310 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
18320 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
18330 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
18340 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
18350 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
18360 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
18370 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
18380 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
18390 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
183a0 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
183b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
183c0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
183d0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
183e0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
183f0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
18400 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
18410 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
18420 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
18430 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
18440 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
18450 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
18460 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
18470 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
18480 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
18490 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
184a0 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
184b0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
184c0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
184d0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
184e0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
184f0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
18500 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
18510 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
18520 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
18530 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
18540 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
18550 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
18560 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
18570 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
18580 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
18590 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
185a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
185b0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
185c0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
185d0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
185e0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
185f0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
18600 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18610 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
18620 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
18630 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
18640 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
18650 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
18660 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  t..*/.sqlite3_in
18670 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
18680 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73  ry_used(void);.s
18690 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
186a0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
186b0 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
186c0 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
186d0 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
186e0 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
186f0 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
18700 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
18710 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
18720 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
18730 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
18740 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
18750 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
18760 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
18770 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
18780 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
18790 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
187a0 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
187b0 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
187c0 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
187d0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
187e0 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
187f0 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
18800 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
18810 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
18820 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
18830 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
18840 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
18850 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
18860 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
18870 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
18880 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
18890 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
188a0 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
188b0 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fer P..**.** ^Th
188c0 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
188d0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
188e0 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
188f0 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
18900 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
18910 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
18920 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
18930 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
18940 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
18950 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
18960 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
18970 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
18980 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75  t..** ^On all su
18990 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
189a0 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
189b0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
189c0 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
189d0 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
189e0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
189f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
18a00 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
18a10 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
18a20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
18a30 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
18a40 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
18a50 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
18a60 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
18a70 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
18a80 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
18a90 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f 72  gisters a author
18aa0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
18ab0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
18ac0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
18ad0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
18ae0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
18af0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
18b00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18b10 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
18b20 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
18b30 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
18b40 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
18b50 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
18b60 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
18b70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18b80 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
18b90 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
18ba0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
18bb0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
18bc0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
18bd0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
18be0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
18bf0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
18c00 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
18c10 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
18c20 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
18c30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
18c40 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
18c50 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
18c60 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
18c70 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
18c80 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
18c90 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
18ca0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
18cb0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
18cc0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
18cd0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
18ce0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
18cf0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
18d00 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
18d10 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
18d20 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
18d30 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
18d40 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
18d50 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
18d60 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
18d70 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
18d80 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
18d90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
18da0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
18db0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
18dc0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
18dd0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
18de0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
18df0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
18e00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
18e10 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
18e20 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
18e30 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
18e40 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
18e50 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
18e60 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
18e70 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
18e80 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
18e90 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
18ea0 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
18eb0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
18ec0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
18ed0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
18ee0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
18ef0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
18f00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
18f10 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
18f20 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
18f30 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
18f40 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
18f50 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
18f60 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
18f70 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
18f80 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
18f90 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
18fa0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
18fb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
18fc0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
18fd0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
18fe0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
18ff0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
19000 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
19010 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19020 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
19030 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
19040 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
19050 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
19060 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
19070 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
19080 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
19090 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
190a0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
190b0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
190c0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
190d0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
190e0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
190f0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
19100 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
19110 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
19120 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
19130 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
19140 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
19150 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
19160 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
19170 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
19180 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
19190 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
191a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
191b0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
191c0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
191d0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
191e0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
191f0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
19200 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
19210 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
19220 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
19230 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
19240 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
19250 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
19260 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
19270 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
19280 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
19290 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
192a0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
192b0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
192c0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
192d0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
192e0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
192f0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
19300 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
19310 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
19320 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
19330 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
19340 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
19350 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
19360 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
19370 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
19380 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
19390 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
193a0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
193b0 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
193c0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
193d0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
193e0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
193f0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
19400 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
19410 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
19420 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
19430 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
19440 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
19450 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
19460 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
19470 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
19480 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
19490 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
194a0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
194b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
194c0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
194d0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
194e0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
194f0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
19500 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
19510 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
19520 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
19530 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
19540 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
19550 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
19560 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
19570 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
19580 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
19590 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
195a0 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
195b0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
195c0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
195d0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
195e0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
195f0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
19600 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
19610 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
19620 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
19630 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
19640 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
19650 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
19660 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
19670 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
19680 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
19690 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
196a0 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
196b0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
196c0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
196d0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
196e0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
196f0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
19700 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
19710 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
19720 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
19730 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
19740 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
19750 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
19760 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
19770 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
19780 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
19790 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
197a0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
197b0 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
197c0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
197d0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
197e0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
197f0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
19800 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
19810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
19820 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
19830 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
19840 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
19850 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
19860 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19870 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
19880 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
19890 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
198a0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
198b0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
198c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
198d0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
198e0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
198f0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
19900 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
19910 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
19920 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
19930 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
19940 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
19950 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
19960 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
19970 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
19980 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
19990 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
199a0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
199b0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
199c0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
199d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
199e0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
199f0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
19a00 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19a10 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
19a20 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
19a30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19a40 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
19a50 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
19a60 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
19a70 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
19a80 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
19a90 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
19aa0 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
19ab0 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
19ac0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
19ad0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
19ae0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
19af0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
19b00 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
19b10 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
19b20 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
19b30 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
19b40 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
19b50 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
19b60 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
19b70 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
19b80 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
19b90 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
19ba0 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
19bb0 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
19bc0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
19bd0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
19be0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
19bf0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
19c00 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
19c10 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
19c20 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
19c30 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
19c40 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
19c50 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
19c60 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
19c70 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
19c80 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
19c90 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
19ca0 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
19cb0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
19cc0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
19cd0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
19ce0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
19cf0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
19d00 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
19d10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
19d20 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
19d30 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
19d40 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
19d50 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
19d60 74 69 6f 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  tion..*/.#define
19d70 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
19d80 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
19d90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
19da0 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
19db0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
19dc0 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
19dd0 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
19de0 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
19df0 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
19e00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19e10 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
19e20 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
19e30 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
19e40 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
19e50 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
19e60 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
19e70 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
19e80 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
19e90 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c  rize certain SQL
19ea0 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
19eb0 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
19ec0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
19ed0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
19ee0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
19ef0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
19f00 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
19f10 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
19f20 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
19f30 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
19f40 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
19f50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19f60 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
19f70 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
19f80 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
19f90 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
19fa0 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
19fb0 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20  ion is to be.** 
19fc0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
19fd0 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
19fe0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
19ff0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
1a000 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1a010 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
1a020 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
1a030 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
1a040 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
1a050 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
1a060 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a070 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61  r.  ^(The 5th pa
1a080 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
1a090 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
1a0a0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
1a0b0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1a0c0 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
1a0d0 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
1a0e0 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54  pplicable.)^  ^T
1a0f0 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
1a100 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1a110 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
1a120 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1a130 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
1a140 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
1a150 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
1a160 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
1a170 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
1a180 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
1a190 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
1a1a0 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
1a1b0 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
1a1c0 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
1a1d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a1e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a1f0 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
1a200 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
1a210 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
1a220 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
1a230 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
1a240 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1a250 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1a260 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a270 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
1a280 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
1a290 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1a2a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1a2b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a2c0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
1a2d0 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
1a2e0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1a2f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1a300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a310 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
1a320 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
1a330 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1a340 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1a350 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1a360 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
1a370 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
1a380 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1a390 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1a3a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1a3b0 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
1a3c0 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
1a3d0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1a3e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1a3f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1a400 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
1a410 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
1a420 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1a430 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1a440 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1a450 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
1a460 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
1a470 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1a480 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1a490 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
1a4a0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1a4b0 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
1a4c0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1a4d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1a4e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
1a4f0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
1a500 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
1a510 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1a520 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1a530 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
1a540 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
1a550 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1a560 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1a570 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1a580 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1a590 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
1a5a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1a5b0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1a5c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1a5d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1a5e0 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
1a5f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1a600 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1a610 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a620 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1a630 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
1a640 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1a650 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1a660 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a670 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
1a680 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
1a690 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1a6a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1a6b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a6c0 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
1a6d0 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
1a6e0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1a6f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1a700 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a710 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
1a720 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
1a730 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1a740 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1a750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a760 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
1a770 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
1a780 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1a790 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1a7a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a7b0 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
1a7c0 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
1a7d0 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
1a7e0 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
1a7f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a800 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
1a810 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
1a820 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1a830 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1a840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1a850 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1a860 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
1a870 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
1a880 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1a890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
1a8a0 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
1a8b0 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
1a8c0 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
1a8d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1a8e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
1a8f0 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
1a900 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
1a910 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1a920 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1a930 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
1a940 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1a950 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
1a960 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
1a970 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1a980 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
1a990 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1a9a0 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
1a9b0 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
1a9c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1a9d0 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
1a9e0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1a9f0 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
1aa00 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
1aa10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1aa20 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
1aa30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
1aa40 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1aa50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1aa60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1aa70 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
1aa80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
1aa90 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1aaa0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1aab0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1aac0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
1aad0 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
1aae0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1aaf0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1ab00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ab10 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
1ab20 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
1ab30 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1ab40 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
1ab50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ab60 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
1ab70 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
1ab80 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1ab90 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
1aba0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1abb0 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
1abc0 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
1abd0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1abe0 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
1abf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ac00 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
1ac10 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
1ac20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
1ac30 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1ac40 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
1ac50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
1ac60 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1ac70 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
1ac80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1ac90 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
1aca0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
1acb0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
1acc0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
1acd0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1ace0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
1acf0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1ad00 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1ad10 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
1ad20 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
1ad30 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
1ad40 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1ad50 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
1ad60 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
1ad70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
1ad80 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1ad90 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1ada0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
1adb0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
1adc0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1add0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
1ade0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
1adf0 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
1ae00 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
1ae10 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1ae20 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
1ae30 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
1ae40 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
1ae50 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
1ae60 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
1ae70 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
1ae80 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
1ae90 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
1aea0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
1aeb0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
1aec0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1aed0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1aee0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
1aef0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
1af00 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
1af10 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
1af20 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
1af30 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
1af40 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
1af50 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
1af60 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
1af70 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
1af80 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
1af90 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
1afa0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
1afb0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1afc0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
1afd0 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
1afe0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
1aff0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
1b000 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
1b010 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
1b020 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
1b030 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
1b040 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
1b050 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
1b060 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
1b070 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
1b080 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1b090 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
1b0a0 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
1b0b0 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
1b0c0 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
1b0d0 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
1b0e0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
1b0f0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
1b100 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
1b110 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
1b120 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
1b130 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
1b140 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1b150 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1b160 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1b170 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1b180 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1b190 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1b1a0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1b1b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1b1c0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1b1d0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1b1e0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1b1f0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1b200 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1b210 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b220 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1b230 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1b240 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
1b250 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
1b260 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
1b270 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
1b280 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1b290 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
1b2a0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
1b2b0 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
1b2c0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
1b2d0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
1b2e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b2f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
1b300 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
1b310 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1b320 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
1b330 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1b340 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1b350 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1b360 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1b370 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1b380 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
1b390 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
1b3a0 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
1b3b0 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
1b3c0 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
1b3d0 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
1b3e0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
1b3f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a   the number of .
1b400 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
1b410 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
1b420 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
1b430 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
1b440 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
1b450 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
1b460 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20  llback X..**.** 
1b470 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
1b480 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1b490 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
1b4a0 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
1b4b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1b4c0 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
1b4d0 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
1b4e0 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
1b4f0 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
1b500 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
1b510 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
1b520 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
1b530 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1b540 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
1b550 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
1b560 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
1b570 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
1b580 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
1b590 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
1b5a0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
1b5b0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1b5c0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
1b5d0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
1b5e0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
1b5f0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
1b600 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
1b610 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
1b620 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
1b630 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
1b640 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
1b650 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1b660 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1b670 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1b680 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1b690 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b6a0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1b6b0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1b6c0 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
1b6d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1b6e0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1b6f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1b700 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1b710 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1b720 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1b730 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1b740 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1b750 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
1b760 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1b770 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
1b780 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
1b790 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
1b7a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b7b0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
1b7c0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
1b7d0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
1b7e0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
1b7f0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
1b800 20 66 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65   file whose name
1b810 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
1b820 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1b830 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
1b840 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1b850 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1b860 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1b870 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1b880 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1b890 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1b8a0 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1b8b0 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1b8c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1b8d0 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
1b8e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1b8f0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1b900 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1b910 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1b920 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1b930 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1b940 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1b950 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1b960 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1b970 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1b980 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1b990 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1b9a0 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1b9b0 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1b9c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1b9d0 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1b9e0 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
1b9f0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1ba00 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1ba10 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
1ba20 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
1ba30 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
1ba40 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
1ba50 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
1ba60 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
1ba70 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
1ba80 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
1ba90 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
1baa0 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
1bab0 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
1bac0 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
1bad0 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
1bae0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
1baf0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
1bb00 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
1bb10 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
1bb20 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
1bb30 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1bb40 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
1bb50 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
1bb60 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
1bb70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
1bb80 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
1bb90 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
1bba0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
1bbb0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
1bbc0 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
1bbd0 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
1bbe0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
1bbf0 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
1bc00 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
1bc10 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
1bc20 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
1bc30 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
1bc40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1bc50 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
1bc60 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
1bc70 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
1bc80 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
1bc90 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
1bca0 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
1bcb0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1bcc0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
1bcd0 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
1bce0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
1bcf0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
1bd00 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
1bd10 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
1bd20 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
1bd30 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
1bd40 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
1bd50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
1bd60 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
1bd70 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
1bd80 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
1bd90 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
1bda0 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
1bdb0 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
1bdc0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
1bdd0 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
1bde0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1bdf0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
1be00 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
1be10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
1be20 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64  EDCACHE],.** and
1be30 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
1be40 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
1be50 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
1be60 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
1be70 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1be80 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
1be90 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1bea0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
1beb0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
1bec0 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
1bed0 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
1bee0 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
1bef0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1bf00 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1bf10 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1bf20 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
1bf30 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1bf40 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1bf50 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1bf60 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
1bf70 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
1bf80 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
1bf90 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
1bfa0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
1bfb0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
1bfc0 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
1bfd0 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
1bfe0 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
1bff0 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
1c000 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
1c010 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
1c020 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
1c030 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
1c040 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
1c050 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
1c060 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1c070 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
1c080 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
1c090 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
1c0a0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
1c0b0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
1c0c0 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
1c0d0 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
1c0e0 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
1c0f0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1c100 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
1c110 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
1c120 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
1c130 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1c140 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1c150 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
1c160 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
1c170 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72  s shown above or
1c180 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62   one of the comb
1c190 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1c1a0 62 6f 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a  bove combined.**
1c1b0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
1c1c0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
1c1d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1c1e0 4c 4c 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51  LLMUTEX],.** [SQ
1c1f0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1c200 43 41 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53  CACHE] and/or [S
1c210 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
1c220 54 45 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a  TECACHE] flags,.
1c230 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ** then the beha
1c240 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
1c250 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
1c260 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f   [SQLITE_OPEN_NO
1c270 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
1c280 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  et, then the dat
1c290 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c2a0 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65  .** opens in the
1c2b0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74   multi-thread [t
1c2c0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
1c2d0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69  s long as the si
1c2e0 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d  ngle-thread.** m
1c2f0 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ode has not been
1c300 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
1c310 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69  time or start-ti
1c320 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  me.  ^If the.** 
1c330 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1c340 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20  LMUTEX] flag is 
1c350 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74  set then the dat
1c360 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c370 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65   opens.** in the
1c380 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   serialized [thr
1c390 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c  eading mode] unl
1c3a0 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  ess single-threa
1c3b0 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75  d was.** previou
1c3c0 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20  sly selected at 
1c3d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20  compile-time or 
1c3e0 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e  start-time..** ^
1c3f0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
1c400 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c  _SHAREDCACHE] fl
1c410 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
1c420 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c430 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69  n to be.** eligi
1c440 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72  ble to use [shar
1c450 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20  ed cache mode], 
1c460 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
1c470 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
1c480 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20  red.** cache is 
1c490 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73  enabled using [s
1c4a0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68  qlite3_enable_sh
1c4b0 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20  ared_cache()].  
1c4c0 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ^The.** [SQLITE_
1c4d0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1c4e0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
1c4f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1c500 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a  ection to not.**
1c510 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
1c520 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
1c530 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69  de] even if it i
1c540 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
1c550 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
1c560 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
1c570 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1c580 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
1c590 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
1c5a0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
1c5b0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
1c5c0 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
1c5d0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
1c5e0 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
1c5f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c600 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1c610 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1c620 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
1c630 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
1c640 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
1c650 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
1c660 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
1c670 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
1c680 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
1c690 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
1c6a0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
1c6b0 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
1c6c0 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
1c6d0 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
1c6e0 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
1c6f0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
1c700 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
1c710 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
1c720 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
1c730 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
1c740 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
1c750 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1c760 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1c770 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
1c780 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
1c790 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
1c7a0 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
1c7b0 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
1c7c0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
1c7d0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
1c7e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1c7f0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1c800 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
1c810 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1c820 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1c830 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
1c840 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
1c850 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1c860 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
1c870 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1c880 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
1c890 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
1c8a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c8b0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
1c8c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
1c8d0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
1c8e0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1c8f0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1c900 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1c910 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1c920 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
1c930 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
1c940 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
1c950 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
1c960 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
1c970 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1c980 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1c990 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
1c9a0 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
1c9b0 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
1c9c0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
1c9d0 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
1c9e0 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
1c9f0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
1ca00 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
1ca10 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
1ca20 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
1ca30 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
1ca40 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
1ca50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ca60 28 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()..*/.int sqlit
1ca70 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
1ca80 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1ca90 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1caa0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1cab0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1cac0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
1cad0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1cae0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
1caf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
1cb00 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
1cb10 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
1cb20 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
1cb30 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
1cb40 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1cb50 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1cb60 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1cb70 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1cb80 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
1cb90 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
1cba0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
1cbb0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
1cbc0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
1cbd0 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
1cbe0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
1cbf0 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
1cc00 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
1cc10 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
1cc20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
1cc30 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
1cc40 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
1cc50 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
1cc60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
1cc70 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
1cc80 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sages.**.** ^The
1cc90 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1cca0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
1ccb0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
1ccc0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
1ccd0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
1cce0 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
1ccf0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
1cd00 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
1cd10 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73   API call.** ass
1cd20 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
1cd30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cd40 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72  ion]. If a prior
1cd50 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
1cd60 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74  .** but the most
1cd70 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
1cd80 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
1cd90 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
1cda0 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72  m.** sqlite3_err
1cdb0 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
1cdc0 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ned.  ^The sqlit
1cdd0 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
1cde0 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
1cdf0 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
1ce00 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
1ce10 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
1ce20 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
1ce30 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
1ce40 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
1ce50 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
1ce60 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
1ce70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1ce80 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
1ce90 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
1cea0 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
1ceb0 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
1cec0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
1ced0 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
1cee0 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
1cef0 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
1cf00 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
1cf10 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
1cf20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
1cf30 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
1cf40 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
1cf50 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
1cf60 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
1cf70 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
1cf80 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
1cf90 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
1cfa0 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
1cfb0 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
1cfc0 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
1cfd0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
1cfe0 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
1cff0 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
1d000 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57  tions.)^.**.** W
1d010 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
1d020 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
1d030 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
1d040 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
1d050 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
1d060 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
1d070 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
1d080 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
1d090 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
1d0a0 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
1d0b0 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
1d0c0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
1d0d0 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
1d0e0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
1d0f0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
1d100 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
1d110 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
1d120 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
1d130 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
1d140 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
1d150 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
1d160 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
1d170 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
1d180 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
1d190 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1d1a0 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
1d1b0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
1d1c0 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
1d1d0 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
1d1e0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
1d1f0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
1d200 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
1d210 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
1d220 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
1d230 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
1d240 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
1d250 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
1d260 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
1d270 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
1d280 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
1d290 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
1d2a0 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
1d2b0 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
1d2c0 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
1d2d0 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
1d2e0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
1d2f0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
1d300 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
1d310 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
1d320 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
1d330 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1d340 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1d350 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
1d360 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1d370 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
1d380 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1d390 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
1d3a0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
1d3b0 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
1d3c0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  g16(sqlite3*);..
1d3d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d3e0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  SQL Statement Ob
1d3f0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
1d400 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  : {prepared stat
1d410 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64  ement} {prepared
1d420 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a   statements}.**.
1d430 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
1d440 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65  f this object re
1d450 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c  presents a singl
1d460 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1d470 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
1d480 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f  is variously kno
1d490 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65  wn as a "prepare
1d4a0 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  d statement" or 
1d4b0 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53  a.** "compiled S
1d4c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  QL statement" or
1d4d0 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74   simply as a "st
1d4e0 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20  atement"..**.** 
1d4f0 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74  The life of a st
1d500 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67  atement object g
1d510 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69  oes something li
1d520 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1d530 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
1d540 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  te the object us
1d550 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
1d560 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20  pare_v2()] or a 
1d570 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20  related.**      
1d580 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  function..** <li
1d590 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
1d5a0 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   [host parameter
1d5b0 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
1d5c0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
1d5d0 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
1d5e0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
1d5f0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
1d600 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d610 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
1d620 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
1d630 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  et the statement
1d640 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1d650 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
1d660 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
1d670 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
1d680 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
1d690 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
1d6a0 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
1d6b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1d6c0 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
1d6d0 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65  </ol>.**.** Refe
1d6e0 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69  r to documentati
1d6f0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
1d700 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66   methods above f
1d710 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
1d720 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
1d730 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
1d740 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
1d750 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
1d760 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
1d770 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a  time Limits.**.*
1d780 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
1d790 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
1d7a0 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
1d7b0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
1d7c0 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
1d7d0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
1d7e0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
1d7f0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1d800 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
1d810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d820 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
1d830 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
1d840 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
1d850 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1d860 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
1d870 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
1d880 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
1d890 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
1d8a0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
1d8b0 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
1d8c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
1d8d0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
1d8e0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
1d8f0 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
1d900 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
1d910 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
1d920 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
1d930 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
1d940 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
1d950 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
1d960 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
1d970 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
1d980 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
1d990 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1d9a0 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
1d9b0 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
1d9c0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
1d9d0 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
1d9e0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
1d9f0 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
1da00 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
1da10 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
1da20 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
1da30 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
1da40 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
1da50 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
1da60 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
1da70 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
1da80 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
1da90 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
1daa0 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
1dab0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1dac0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
1dad0 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
1dae0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
1daf0 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
1db00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
1db10 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
1db20 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
1db30 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
1db40 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
1db50 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
1db60 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
1db70 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
1db80 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
1db90 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
1dba0 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
1dbb0 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
1dbc0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
1dbd0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
1dbe0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
1dbf0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
1dc00 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
1dc10 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
1dc20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
1dc30 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
1dc40 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
1dc50 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
1dc60 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
1dc70 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
1dc80 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
1dc90 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
1dca0 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
1dcb0 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
1dcc0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
1dcd0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
1dce0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
1dcf0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
1dd00 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
1dd10 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
1dd20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
1dd30 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
1dd40 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
1dd50 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
1dd60 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
1dd70 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
1dd80 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
1dd90 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
1dda0 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
1ddb0 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
1ddc0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
1ddd0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
1dde0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
1ddf0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
1de00 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
1de10 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1de20 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
1de30 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
1de40 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
1de50 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
1de60 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
1de70 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
1de80 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
1de90 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
1dea0 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
1deb0 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
1dec0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
1ded0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
1dee0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
1def0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
1df00 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
1df10 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ases..*/.int sql
1df20 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
1df30 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
1df40 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
1df50 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1df60 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
1df70 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
1df80 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
1df90 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
1dfa0 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
1dfb0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
1dfc0 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
1dfd0 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
1dfe0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
1dff0 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
1e000 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
1e010 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
1e020 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
1e030 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
1e040 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
1e050 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
1e060 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
1e070 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
1e080 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
1e090 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
1e0a0 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
1e0b0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  l>.** ^(<dt>SQLI
1e0c0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
1e0d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e0e0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
1e0f0 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
1e100 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
1e110 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
1e120 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1e130 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
1e140 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1e150 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e  >The maximum len
1e160 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74  gth of an SQL st
1e170 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65  atement, in byte
1e180 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
1e190 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1e1a0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
1e1b0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e1c0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
1e1d0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
1e1e0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
1e1f0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
1e200 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
1e210 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
1e220 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
1e230 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
1e240 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
1e250 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
1e260 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
1e270 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1e280 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
1e290 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1e2a0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
1e2b0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
1e2c0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
1e2d0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
1e2e0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1e2f0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1e300 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
1e310 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1e320 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
1e330 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
1e340 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
1e350 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1e360 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
1e370 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
1e380 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1e390 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
1e3a0 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
1e3b0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
1e3c0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
1e3d0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
1e3e0 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
1e3f0 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
1e400 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
1e410 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
1e420 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
1e430 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
1e440 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
1e450 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1e460 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1e470 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
1e480 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
1e490 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
1e4a0 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
1e4b0 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
1e4c0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1e4d0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
1e4e0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
1e4f0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1e500 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
1e510 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
1e520 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
1e530 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
1e540 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
1e550 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
1e560 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
1e570 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
1e580 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
1e590 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
1e5a0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
1e5b0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
1e5c0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1e5d0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1e5e0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
1e5f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
1e600 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
1e610 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
1e620 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
1e630 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1e640 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
1e650 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
1e660 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e670 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
1e680 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
1e690 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  s.</dd>)^.** </d
1e6a0 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
1e6b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
1e6c0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1e6d0 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
1e6e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
1e6f0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
1e700 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
1e710 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
1e720 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
1e730 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
1e740 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
1e750 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
1e760 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
1e770 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
1e780 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
1e790 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
1e7a0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1e7b0 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
1e7c0 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
1e7d0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1e7e0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
1e7f0 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
1e800 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1e810 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
1e820 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
1e830 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1e840 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
1e850 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
1e860 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1e870 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
1e880 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
1e890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1e8a0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
1e8b0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
1e8c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e8d0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
1e8e0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
1e8f0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
1e900 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
1e910 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
1e920 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
1e930 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
1e940 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
1e950 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
1e960 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
1e970 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
1e980 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
1e990 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
1e9a0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
1e9b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1e9c0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
1e9d0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
1e9e0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
1e9f0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
1ea00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1ea10 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1ea20 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
1ea30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ea40 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
1ea50 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
1ea60 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
1ea70 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
1ea80 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
1ea90 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
1eaa0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
1eab0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
1eac0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
1ead0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1eae0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1eaf0 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
1eb00 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
1eb10 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
1eb20 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
1eb30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1eb40 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
1eb50 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
1eb60 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
1eb70 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a  t is less than z
1eb80 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ero, then zSql i
1eb90 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
1eba0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
1ebb0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
1ebc0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
1ebd0 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73  tive, then it is
1ebe0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
1ebf0 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73  number of  bytes
1ec00 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
1ec10 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73    ^When nByte is
1ec20 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
1ec30 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e  he.** zSql strin
1ec40 67 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72  g ends at either
1ec50 20 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30   the first '\000
1ec60 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68  ' or '\u0000' ch
1ec70 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68  aracter or.** th
1ec80 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c  e nByte-th byte,
1ec90 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
1eca0 20 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63   first. If the c
1ecb0 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74  aller knows.** t
1ecc0 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64  hat the supplied
1ecd0 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74   string is nul-t
1ece0 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20  erminated, then 
1ecf0 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
1ed00 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  .** performance 
1ed10 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20  advantage to be 
1ed20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e  gained by passin
1ed30 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
1ed40 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
1ed50 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d  equal to the num
1ed60 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
1ed70 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1ed80 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
1ed90 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
1eda0 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 2e 0a 2a  minator bytes..*
1edb0 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
1edc0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
1edd0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
1ede0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
1edf0 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
1ee00 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
1ee10 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
1ee20 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
1ee30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1ee40 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
1ee50 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
1ee60 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
1ee70 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
1ee80 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
1ee90 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
1eea0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
1eeb0 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
1eec0 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
1eed0 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
1eee0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1eef0 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
1ef00 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1ef10 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
1ef20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
1ef30 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
1ef40 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
1ef50 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
1ef60 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
1ef70 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
1ef80 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
1ef90 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
1efa0 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
1efb0 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
1efc0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
1efd0 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
1efe0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
1eff0 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
1f000 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
1f010 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
1f020 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
1f030 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
1f040 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
1f050 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
1f060 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
1f070 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
1f080 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1f090 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
1f0a0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
1f0b0 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
1f0c0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
1f0d0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
1f0e0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
1f0f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f100 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
1f110 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
1f120 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
1f130 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
1f140 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
1f150 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
1f160 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
1f170 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
1f180 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1f190 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
1f1a0 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
1f1b0 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
1f1c0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
1f1d0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
1f1e0 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
1f1f0 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
1f200 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
1f210 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
1f220 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
1f230 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
1f240 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
1f250 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
1f260 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
1f270 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
1f280 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
1f290 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
1f2a0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
1f2b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
1f2c0 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
1f2d0 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
1f2e0 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
1f2f0 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
1f300 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
1f310 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f320 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
1f330 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
1f340 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
1f350 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
1f360 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c  n it again..** <
1f370 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
1f380 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
1f390 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
1f3a0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
1f3b0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
1f3c0 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
1f3d0 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
1f3e0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
1f3f0 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
1f400 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
1f410 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
1f420 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
1f430 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
1f440 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
1f450 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
1f460 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
1f470 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
1f480 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
1f490 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
1f4a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
1f4b0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
1f4c0 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
1f4d0 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
1f4e0 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
1f4f0 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
1f500 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
1f510 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
1f520 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
1f530 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1f540 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
1f550 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
1f560 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63  ^If the specific
1f570 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20   value bound to 
1f580 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
1f590 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
1f5a0 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c  the .** WHERE cl
1f5b0 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75  ause might influ
1f5c0 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20  ence the choice 
1f5d0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  of query plan fo
1f5e0 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a  r a statement,.*
1f5f0 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  * then the state
1f600 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74  ment will be aut
1f610 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
1f620 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65  piled, as if the
1f630 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20  re had been .** 
1f640 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  a schema change,
1f650 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b   on the first  [
1f660 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f670 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
1f680 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20  ny change.** to 
1f690 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
1f6a0 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
1f6b0 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61  s] of that [para
1f6c0 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65  meter]. .** ^The
1f6d0 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
1f6e0 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20  of WHERE-clause 
1f6f0 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68  [parameter] migh
1f700 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
1f710 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75  .** choice of qu
1f720 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20  ery plan if the 
1f730 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
1f740 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
1f750 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f  of a [LIKE].** o
1f760 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  r [GLOB] operato
1f770 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61  r or if the para
1f780 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65  meter is compare
1f790 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20  d to an indexed 
1f7a0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68  column.** and th
1f7b0 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
1f7c0 5f 53 54 41 54 32 5d 20 63 6f 6d 70 69 6c 65 2d  _STAT2] compile-
1f7d0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
1f7e0 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a  nabled..** the .
1f7f0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
1f800 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  >.*/.int sqlite3
1f810 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
1f820 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1f830 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1f840 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1f850 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1f860 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1f870 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1f880 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1f890 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1f8a0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1f8b0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1f8c0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1f8d0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1f8e0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1f8f0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1f900 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1f910 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1f920 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1f930 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1f940 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
1f950 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a  te3_prepare_v2(.
1f960 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1f970 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1f980 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1f990 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1f9a0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1f9b0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1f9c0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
1f9d0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1f9e0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1f9f0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1fa00 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1fa10 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1fa20 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1fa30 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1fa40 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
1fa50 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1fa60 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1fa70 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1fa80 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
1fa90 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
1faa0 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  e16(.  sqlite3 *
1fab0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
1fac0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
1fad0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1fae0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
1faf0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
1fb00 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
1fb10 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
1fb20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
1fb30 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
1fb40 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
1fb50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
1fb60 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
1fb70 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
1fb80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1fb90 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
1fba0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
1fbb0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
1fbc0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
1fbd0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
1fbe0 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
1fbf0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1fc00 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
1fc10 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
1fc20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
1fc30 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
1fc40 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
1fc50 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
1fc60 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
1fc70 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
1fc80 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
1fc90 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
1fca0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
1fcb0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
1fcc0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
1fcd0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
1fce0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
1fcf0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
1fd00 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
1fd10 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
1fd20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
1fd30 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
1fd40 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
1fd50 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
1fd60 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
1fd70 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
1fd80 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
1fd90 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
1fda0 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
1fdb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1fdc0 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
1fdd0 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
1fde0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
1fdf0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
1fe00 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
1fe10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
1fe20 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  v2()]..*/.const 
1fe30 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
1fe40 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
1fe50 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
1fe60 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
1fe70 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
1fe80 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
1fe90 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a  e Database.**.**
1fea0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
1feb0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
1fec0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
1fed0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
1fee0 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
1fef0 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
1ff00 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
1ff10 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
1ff20 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
1ff30 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
1ff40 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
1ff50 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
1ff60 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
1ff70 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
1ff80 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
1ff90 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
1ffa0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
1ffb0 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
1ffc0 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
1ffd0 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
1ffe0 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
1fff0 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
20000 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
20010 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
20020 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
20030 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
20040 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
20050 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
20060 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
20070 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
20080 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
20090 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
200a0 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
200b0 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
200c0 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
200d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
200e0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
200f0 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
20100 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
20110 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
20120 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
20130 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
20140 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
20150 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
20160 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
20170 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
20180 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
20190 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
201a0 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
201b0 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
201c0 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
201d0 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
201e0 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
201f0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
20200 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
20210 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
20220 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
20230 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
20240 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
20250 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
20260 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
20270 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
20280 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
20290 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
202a0 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
202b0 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
202c0 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
202d0 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
202e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
202f0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
20300 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
20310 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
20320 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
20330 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
20340 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
20350 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
20360 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
20370 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
20380 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
20390 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
203a0 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  disk..*/.int sql
203b0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
203c0 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
203d0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
203e0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
203f0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
20400 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
20410 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
20420 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
20430 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
20440 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
20450 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
20460 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
20470 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
20480 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
20490 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
204a0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
204b0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
204c0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
204d0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
204e0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
204f0 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
20500 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
20510 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
20520 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
20530 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
20540 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
20550 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
20560 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
20570 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
20580 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
20590 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
205a0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
205b0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
205c0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
205d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
205e0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
205f0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
20600 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
20610 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
20620 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
20630 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
20640 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
20650 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
20660 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
20670 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
20680 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
20690 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
206a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
206b0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
206c0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
206d0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
206e0 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
206f0 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
20700 69 73 20 68 65 6c 64 2e 20 20 41 20 69 6e 74 65  is held.  A inte
20710 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
20720 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
20730 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
20740 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
20750 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
20760 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
20770 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
20780 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
20790 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
207a0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
207b0 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
207c0 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
207d0 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
207e0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
207f0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
20800 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
20810 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
20820 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
20830 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
20840 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
20850 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
20860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
20870 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
20880 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
20890 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
208a0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
208b0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
208c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
208d0 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
208e0 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
208f0 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
20900 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
20910 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
20920 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
20930 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
20940 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
20950 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
20960 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
20970 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
20980 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
20990 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
209a0 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
209b0 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
209c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
209d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
209e0 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
209f0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
20a00 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
20a10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
20a20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
20a30 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
20a40 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
20a50 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
20a60 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
20a70 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
20a80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
20a90 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
20aa0 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
20ab0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
20ac0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
20ad0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
20ae0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
20af0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
20b00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
20b10 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
20b20 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
20b30 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
20b40 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
20b50 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
20b60 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
20b70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20b80 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
20b90 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
20ba0 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
20bb0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
20bc0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
20bd0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
20be0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
20bf0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
20c00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
20c10 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
20c20 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
20c30 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
20c40 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
20c50 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
20c60 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
20c70 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
20c80 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
20c90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
20ca0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
20cb0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
20cc0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
20cd0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
20ce0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
20cf0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
20d00 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
20d10 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
20d20 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
20d30 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
20d40 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
20d50 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
20d60 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
20d70 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
20d80 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
20d90 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
20da0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
20db0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
20dc0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
20dd0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
20de0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
20df0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
20e00 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
20e10 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
20e20 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
20e30 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
20e40 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
20e50 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
20e60 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
20e70 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
20e80 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
20e90 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
20ea0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
20eb0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
20ec0 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
20ed0 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
20ee0 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
20ef0 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
20f00 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
20f10 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
20f20 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
20f30 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
20f40 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
20f50 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
20f60 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
20f70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
20f80 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
20f90 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
20fa0 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
20fb0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
20fc0 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
20fd0 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
20fe0 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
20ff0 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
21000 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
21010 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
21020 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
21030 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
21040 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
21050 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
21060 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
21070 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
21080 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
21090 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
210a0 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
210b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
210c0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
210d0 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
210e0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
210f0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
21100 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
21110 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
21120 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
21130 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
21140 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
21150 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
21160 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21170 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
21180 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
21190 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
211a0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
211b0 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
211c0 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
211d0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
211e0 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
211f0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
21200 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
21210 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
21220 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
21230 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
21240 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
21250 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
21260 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
21270 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
21280 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
21290 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
212a0 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
212b0 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
212c0 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
212d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
212e0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
212f0 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
21300 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
21310 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
21320 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
21330 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
21340 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
21350 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
21360 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
21370 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
21380 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
21390 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
213a0 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
213b0 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
213c0 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
213d0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
213e0 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
213f0 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
21400 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
21410 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
21420 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
21430 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
21440 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
21450 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
21460 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
21470 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
21480 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
21490 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
214a0 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
214b0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
214c0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
214d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
214e0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
214f0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 20 6c 65  negative, the le
21500 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
21510 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
21520 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
21530 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
21540 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
21550 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
21560 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
21570 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20  e3_bind_blob(), 
21580 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
21590 74 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  t(), and.** sqli
215a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
215b0 29 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  ) is a destructo
215c0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
215d0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
215e0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
215f0 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
21600 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
21610 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
21620 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
21630 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
21640 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
21650 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
21660 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
21670 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ob(),.** sqlite3
21680 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72  _bind_text(), or
21690 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
216a0 78 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a  xt16() fails.  .
216b0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
216c0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
216d0 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
216e0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
216f0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
21700 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
21710 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
21720 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
21730 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
21740 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
21750 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
21760 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
21770 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
21780 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
21790 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
217a0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
217b0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
217c0 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
217d0 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
217e0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
217f0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
21800 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
21810 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
21820 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
21830 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
21840 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
21850 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
21860 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
21870 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
21880 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
21890 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
218a0 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
218b0 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
218c0 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
218d0 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
218e0 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
218f0 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
21900 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
21910 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
21920 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
21930 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
21940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
21950 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
21960 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
21970 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
21980 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
21990 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
219a0 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
219b0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
219c0 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
219d0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
219e0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
219f0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
21a00 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
21a10 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
21a20 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
21a30 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
21a40 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
21a50 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
21a60 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
21a70 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
21a80 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
21a90 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
21aa0 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
21ab0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
21ac0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
21ad0 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
21ae0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
21af0 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
21b00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
21b10 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
21b20 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
21b30 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
21b40 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
21b50 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
21b60 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
21b70 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
21b80 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
21b90 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
21ba0 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
21bb0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
21bc0 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
21bd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
21be0 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
21bf0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
21c00 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
21c10 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
21c20 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
21c30 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
21c40 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20  QLITE_RANGE] is 
21c50 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
21c60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64  parameter.** ind
21c70 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
21c80 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f  ge.  ^[SQLITE_NO
21c90 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64  MEM] is returned
21ca0 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69   if malloc() fai
21cb0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ls..**.** See al
21cc0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
21cd0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
21ce0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
21cf0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21d00 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _name()], and [s
21d10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21d20 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
21d30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
21d40 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ind_blob(sqlite3
21d50 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
21d60 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c  st void*, int n,
21d70 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
21d80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
21d90 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
21da0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
21db0 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74  uble);.int sqlit
21dc0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
21dd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
21de0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
21df0 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
21e00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
21e10 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
21e20 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
21e30 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
21e40 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20  tmt*, int);.int 
21e50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
21e60 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
21e70 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
21e80 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
21e90 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
21ea0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
21eb0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
21ec0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
21ed0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
21ee0 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71  (void*));.int sq
21ef0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
21f00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21f10 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
21f20 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
21f30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
21f40 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
21f50 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
21f60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21f70 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c  F: Number Of SQL
21f80 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
21f90 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
21fa0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
21fb0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
21fc0 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
21fd0 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
21fe0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
21ff0 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
22000 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
22010 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
22020 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
22030 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
22040 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
22050 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
22060 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
22070 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
22080 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
22090 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
220a0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
220b0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
220c0 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
220d0 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
220e0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
220f0 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
22100 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
22110 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
22120 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
22130 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
22140 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
22150 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
22160 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
22170 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
22180 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
22190 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
221a0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
221b0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
221c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
221d0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
221e0 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
221f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22200 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
22210 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
22220 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
22230 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
22240 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
22250 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
22260 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
22270 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
22280 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
22290 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  er.**.** ^The sq
222a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
222b0 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69  eter_name(P,N) i
222c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
222d0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
222e0 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61  the N-th [SQL pa
222f0 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20  rameter] in the 
22300 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22310 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c  ent] P..** ^(SQL
22320 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
22330 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f  he form "?NNN" o
22340 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
22350 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
22360 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63  have a name whic
22370 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20  h is the string 
22380 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
22390 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
223a0 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69  AAA".** respecti
223b0 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65  vely..** In othe
223c0 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69  r words, the ini
223d0 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20  tial ":" or "$" 
223e0 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a  or "@" or "?".**
223f0 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20   is included as 
22400 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65  part of the name
22410 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65  .)^.** ^Paramete
22420 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
22430 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c  ?" without a fol
22440 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68  lowing integer h
22450 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61  ave no name.** a
22460 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20  nd are referred 
22470 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22  to as "nameless"
22480 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70   or "anonymous p
22490 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a  arameters"..**.*
224a0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73  * ^The first hos
224b0 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  t parameter has 
224c0 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e  an index of 1, n
224d0 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ot 0..**.** ^If 
224e0 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f  the value N is o
224f0 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69  ut of range or i
22500 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d  f the N-th param
22510 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c  eter is.** namel
22520 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69  ess, then NULL i
22530 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68  s returned.  ^Th
22540 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
22550 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69  g is.** always i
22560 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  n UTF-8 encoding
22570 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d   even if the nam
22580 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73  ed parameter was
22590 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73  .** originally s
225a0 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d  pecified as UTF-
225b0 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70  16 in [sqlite3_p
225c0 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a  repare16()] or.*
225d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
225e0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
225f0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
22600 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
22610 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
22620 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
22630 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
22640 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
22650 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
22660 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
22670 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
22680 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
22690 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
226a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
226b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
226c0 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
226d0 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
226e0 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74   Name.**.** ^Ret
226f0 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66  urn the index of
22700 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65   an SQL paramete
22710 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65  r given its name
22720 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78  .  ^The.** index
22730 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
22740 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20  is suitable for 
22750 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e  use as the secon
22760 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
22770 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  o [sqlite3_bind_
22780 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
22790 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a  d()].  ^A zero.*
227a0 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  * is returned if
227b0 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72   no matching par
227c0 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e  ameter is found.
227d0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
227e0 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65  .** name must be
227f0 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20   given in UTF-8 
22800 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67  even if the orig
22810 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a  inal statement.*
22820 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66  * was prepared f
22830 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20  rom UTF-16 text 
22840 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
22850 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
22860 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
22870 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
22880 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
22890 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
228a0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
228b0 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
228c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
228d0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
228e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
228f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
22900 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
22910 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
22920 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
22930 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
22940 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
22950 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
22960 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  ment.**.** ^Cont
22970 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
22980 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
22990 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
229a0 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
229b0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
229c0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
229d0 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
229e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
229f0 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
22a00 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
22a10 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
22a20 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  rs to NULL..*/.i
22a30 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
22a40 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
22a50 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
22a60 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
22a70 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
22a80 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a  A Result Set.**.
22a90 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
22aa0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
22ab0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
22ac0 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
22ad0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
22ae0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69  statement]. ^Thi
22af0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
22b00 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73 20  s 0 if pStmt is 
22b10 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  an SQL.** statem
22b20 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  ent that does no
22b30 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28 66  t return data (f
22b40 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55  or example an [U
22b50 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  PDATE])..**.** S
22b60 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
22b70 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
22b80 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
22b90 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
22ba0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
22bb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22bc0 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
22bd0 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
22be0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
22bf0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
22c00 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
22c10 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
22c20 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
22c30 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
22c40 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
22c50 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
22c60 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
22c70 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
22c80 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
22c90 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
22ca0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
22cb0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
22cc0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
22cd0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
22ce0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
22cf0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
22d00 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
22d10 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
22d20 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
22d30 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
22d40 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
22d50 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
22d60 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
22d70 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
22d80 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
22d90 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
22da0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
22db0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
22dc0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
22dd0 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
22de0 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
22df0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
22e00 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
22e10 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
22e20 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
22e30 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
22e40 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
22e50 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
22e60 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
22e70 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
22e80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
22e90 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
22ea0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
22eb0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
22ec0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
22ed0 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
22ee0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
22ef0 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
22f00 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
22f10 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
22f20 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
22f30 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
22f40 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
22f50 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
22f60 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
22f70 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
22f80 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
22f90 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
22fa0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
22fb0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
22fc0 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
22fd0 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
22fe0 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
22ff0 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
23000 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
23010 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
23020 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
23030 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
23040 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
23050 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
23060 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
23070 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
23080 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
23090 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
230a0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
230b0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
230c0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
230d0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
230e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
230f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
23100 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
23110 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
23120 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
23130 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
23140 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Result.**.** ^Th
23150 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f  ese routines pro
23160 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20  vide a means to 
23170 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61  determine the da
23180 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
23190 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75  nd.** table colu
231a0 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f  mn that is the o
231b0 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69  rigin of a parti
231c0 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c  cular result col
231d0 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43  umn in.** [SELEC
231e0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  T] statement..**
231f0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
23200 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61  e database or ta
23210 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61  ble or column ca
23220 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73  n be returned as
23230 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46  .** either a UTF
23240 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  -8 or UTF-16 str
23250 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61  ing.  ^The _data
23260 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  base_ routines r
23270 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74  eturn.** the dat
23280 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20  abase name, the 
23290 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73  _table_ routines
232a0 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c   return the tabl
232b0 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74  e name, and.** t
232c0 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69  he origin_ routi
232d0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63  nes return the c
232e0 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e  olumn name..** ^
232f0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
23300 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ing is valid unt
23310 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  il the [prepared
23320 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64   statement] is d
23330 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e  estroyed.** usin
23340 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
23350 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20  ize()] or until 
23360 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
23370 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
23380 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20  * reprepared by 
23390 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74  the first call t
233a0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
233b0 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  )] for a particu
233c0 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e  lar run.** or un
233d0 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
233e0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
233f0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
23400 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
23410 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
23420 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
23430 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
23440 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
23450 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
23460 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
23470 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
23480 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
23490 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
234a0 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
234b0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
234c0 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
234d0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
234e0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
234f0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
23500 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
23510 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
23520 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
23530 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
23540 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
23550 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
23560 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
23570 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
23580 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
23590 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
235a0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
235b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
235c0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
235d0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
235e0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
235f0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
23600 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
23610 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
23620 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
23630 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
23640 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
23650 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
23660 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
23670 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
23680 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
23690 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
236a0 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
236b0 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
236c0 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
236d0 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
236e0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
236f0 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
23700 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
23710 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
23720 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
23730 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
23740 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
23750 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
23760 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
23770 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
23780 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
23790 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
237a0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
237b0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
237c0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
237d0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
237e0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
237f0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
23800 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
23810 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
23820 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
23830 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
23840 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
23850 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
23860 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
23870 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
23880 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
23890 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
238a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
238b0 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
238c0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
238d0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
238e0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
238f0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
23900 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
23910 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
23920 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23930 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
23940 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
23950 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
23960 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
23970 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63   undefined..*/.c
23980 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
23990 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
239a0 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
239b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
239c0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
239d0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
239e0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
239f0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
23a00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
23a10 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
23a20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
23a30 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
23a40 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23a50 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
23a60 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
23a70 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
23a80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
23a90 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
23aa0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
23ab0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
23ac0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
23ad0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
23ae0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
23af0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
23b00 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
23b10 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
23b20 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
23b30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
23b40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23b50 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
23b60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
23b70 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
23b80 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
23b90 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
23ba0 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
23bb0 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
23bc0 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
23bd0 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
23be0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
23bf0 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
23c00 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
23c10 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
23c20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
23c30 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
23c40 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
23c50 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
23c60 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
23c70 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
23c80 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
23c90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
23ca0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
23cb0 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
23cc0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
23cd0 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
23ce0 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
23cf0 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
23d00 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
23d10 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
23d20 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
23d30 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
23d40 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
23d50 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
23d60 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
23d70 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
23d80 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
23d90 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
23da0 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
23db0 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
23dc0 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
23dd0 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
23de0 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
23df0 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
23e00 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
23e10 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
23e20 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
23e30 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
23e40 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
23e50 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
23e60 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
23e70 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
23e80 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
23e90 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
23ea0 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
23eb0 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
23ec0 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
23ed0 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
23ee0 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
23ef0 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
23f00 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
23f10 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
23f20 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
23f30 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
23f40 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
23f50 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
23f60 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
23f70 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
23f80 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
23f90 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
23fa0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
23fb0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
23fc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
23fd0 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
23fe0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
23ff0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
24000 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
24010 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65  ement.**.** Afte
24020 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  r a [prepared st
24030 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65  atement] has bee
24040 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67  n prepared using
24050 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69   either.** [sqli
24060 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24070 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
24080 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
24090 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61   one of the lega
240a0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
240b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
240c0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
240d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74  _prepare16()], t
240e0 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  his function.** 
240f0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f  must be called o
24100 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
24110 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65   to evaluate the
24120 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a   statement..**.*
24130 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66  * The details of
24140 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
24150 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65   the sqlite3_ste
24160 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65  p() interface de
24170 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  pend.** on wheth
24180 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  er the statement
24190 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73   was prepared us
241a0 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76  ing the newer "v
241b0 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  2" interface.** 
241c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
241d0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
241e0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
241f0 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72  ()] or the older
24200 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
24210 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72  face [sqlite3_pr
24220 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
24230 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
24240 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  )].  The use of 
24250 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20  the.** new "v2" 
24260 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
24270 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77  ommended for new
24280 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75   applications bu
24290 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  t the legacy.** 
242a0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63  interface will c
242b0 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75  ontinue to be su
242c0 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  pported..**.** ^
242d0 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  In the legacy in
242e0 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74  terface, the ret
242f0 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62  urn value will b
24300 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  e either [SQLITE
24310 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  _BUSY],.** [SQLI
24320 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  TE_DONE], [SQLIT
24330 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f  E_ROW], [SQLITE_
24340 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49  ERROR], or [SQLI
24350 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e  TE_MISUSE]..** ^
24360 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e  With the "v2" in
24370 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20  terface, any of 
24380 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c  the other [resul
24390 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b  t codes] or.** [
243a0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
243b0 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20  codes] might be 
243c0 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c  returned as well
243d0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
243e0 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61  _BUSY] means tha
243f0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  t the database e
24400 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65  ngine was unable
24410 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a   to acquire the.
24420 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b  ** database lock
24430 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f  s it needs to do
24440 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74   its job.  ^If t
24450 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
24460 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72  a [COMMIT].** or
24470 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20   occurs outside 
24480 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  of an explicit t
24490 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
244a0 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74   you can retry t
244b0 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e  he.** statement.
244c0 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65    If the stateme
244d0 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d  nt is not a [COM
244e0 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20  MIT] and occurs 
244f0 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70 6c  within a.** expl
24500 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
24510 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
24520 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
24530 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
24540 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
24550 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
24560 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
24570 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
24580 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
24590 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
245a0 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
245b0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
245c0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
245d0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
245e0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
245f0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
24600 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
24610 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
24620 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
24630 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
24640 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
24650 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
24660 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
24670 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
24680 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
24690 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
246a0 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
246b0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
246c0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
246d0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
246e0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
246f0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
24700 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
24710 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
24720 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
24730 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
24740 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
24750 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
24760 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
24770 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
24780 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
24790 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
247a0 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
247b0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
247c0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
247d0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
247e0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
247f0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
24800 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
24810 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
24820 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
24830 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
24840 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
24850 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
24860 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
24870 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
24880 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
24890 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
248a0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
248b0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
248c0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
248d0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
248e0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
248f0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
24900 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
24910 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
24920 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
24930 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
24940 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
24950 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
24960 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
24970 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
24980 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
24990 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
249a0 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
249b0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
249c0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
249d0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
249e0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
249f0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
24a00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24a10 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
24a20 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
24a30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
24a40 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
24a50 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
24a60 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
24a70 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
24a80 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
24a90 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
24aa0 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
24ab0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
24ac0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24ad0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
24ae0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
24af0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
24b00 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
24b10 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
24b20 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
24b30 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
24b40 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
24b50 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
24b60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
24b70 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
24b80 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
24b90 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
24ba0 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
24bb0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
24bc0 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
24bd0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
24be0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
24bf0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
24c00 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
24c10 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
24c20 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
24c30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
24c40 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
24c50 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
24c60 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
24c70 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
24c80 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
24c90 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
24ca0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
24cb0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
24cc0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24cd0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
24ce0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
24cf0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
24d00 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
24d10 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
24d20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
24d30 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
24d40 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
24d50 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
24d60 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
24d70 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
24d80 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
24d90 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
24da0 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
24db0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
24dc0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
24dd0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
24de0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
24df0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
24e00 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
24e10 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
24e20 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
24e30 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
24e40 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
24e50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
24e60 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
24e70 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
24e80 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
24e90 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
24ea0 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
24eb0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
24ec0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
24ed0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
24ee0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
24ef0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24f00 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
24f10 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
24f20 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
24f30 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
24f40 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
24f50 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
24f60 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
24f70 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
24f80 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
24f90 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
24fa0 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
24fb0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
24fc0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
24fd0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
24fe0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
24ff0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
25000 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
25010 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
25020 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
25030 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
25040 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
25050 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
25060 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
25070 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
25080 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
25090 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
250a0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
250b0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
250c0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
250d0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
250e0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
250f0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
25100 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
25110 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ended..*/.int sq
25120 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
25130 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
25140 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
25150 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
25160 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
25170 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
25180 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
25190 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
251a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
251b0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
251c0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
251d0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
251e0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
251f0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
25200 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25210 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
25220 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
25230 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
25240 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
25250 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
25260 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
25270 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
25280 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
25290 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
252a0 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
252b0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
252c0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
252d0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
252e0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
252f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
25300 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
25310 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
25320 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
25330 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
25340 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
25350 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
25360 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
25370 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
25380 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
25390 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
253a0 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
253b0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
253c0 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
253d0 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
253e0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
253f0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
25400 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
25410 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
25420 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
25430 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
25440 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
25450 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
25460 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
25470 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
25480 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
25490 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
254a0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
254b0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
254c0 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
254d0 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
254e0 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
254f0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
25500 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
25510 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
25520 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
25530 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
25540 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
25550 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
25560 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
25570 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
25580 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
25590 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
255a0 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
255b0 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
255c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
255d0 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
255e0 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
255f0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
25600 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
25610 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
25620 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
25630 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
25640 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
25650 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
25660 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
25670 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
25680 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
25690 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
256a0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
256b0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
256c0 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
256d0 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
256e0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
256f0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
25700 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
25710 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
25720 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
25730 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
25740 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
25750 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
25760 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
25770 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
25780 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
25790 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
257a0 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
257b0 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
257c0 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
257d0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
257e0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
257f0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
25800 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
25810 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
25820 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
25830 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
25840 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
25850 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
25860 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
25870 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
25880 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
25890 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
258a0 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
258b0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
258c0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
258d0 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
258e0 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
258f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
25900 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
25910 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
25920 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
25930 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
25940 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
25950 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
25960 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
25970 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
25980 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
25990 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
259a0 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
259b0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
259c0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
259d0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
259e0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
259f0 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
25a00 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
25a10 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
25a20 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
25a30 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
25a40 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
25a50 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
25a60 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
25a70 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
25a80 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
25a90 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
25aa0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
25ab0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
25ac0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25ad0 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
25ae0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
25af0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
25b00 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
25b10 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
25b20 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
25b30 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
25b40 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
25b50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
25b60 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
25b70 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
25b80 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
25b90 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
25ba0 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
25bb0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
25bc0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
25bd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
25be0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
25bf0 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
25c00 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
25c10 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
25c20 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
25c30 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
25c40 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
25c50 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
25c60 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
25c70 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
25c80 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
25c90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
25ca0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
25cb0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
25cc0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
25cd0 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
25ce0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
25cf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
25d00 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
25d10 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
25d20 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
25d30 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
25d40 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
25d50 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
25d60 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
25d70 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
25d80 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
25d90 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
25da0 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
25db0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
25dc0 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
25dd0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
25de0 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
25df0 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
25e00 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
25e10 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
25e20 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
25e30 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
25e40 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
25e50 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25e60 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
25e70 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
25e80 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
25e90 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
25ea0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
25eb0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
25ec0 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
25ed0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
25ee0 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
25ef0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
25f00 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
25f10 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
25f20 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
25f30 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
25f40 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
25f50 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
25f60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
25f70 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
25f80 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
25f90 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
25fa0 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
25fb0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
25fc0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
25fd0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
25fe0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
25ff0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
26000 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
26010 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
26020 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
26030 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
26040 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
26050 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
26060 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
26070 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
26080 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
26090 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
260a0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
260b0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
260c0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
260d0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
260e0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
260f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
26100 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
26110 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
26120 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
26130 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
26140 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
26150 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
26160 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
26170 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
26180 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
26190 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
261a0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
261b0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
261c0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
261d0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
261e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
261f0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
26200 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
26210 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
26220 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
26230 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
26240 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
26250 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
26260 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
26270 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
26280 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
26290 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
262a0 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
262b0 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
262c0 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
262d0 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
262e0 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
262f0 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
26300 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
26310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
26320 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
26330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
26340 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
26350 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
26360 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
26370 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
26380 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
26390 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
263a0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
263b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
263c0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
263d0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
263e0 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
263f0 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
26400 65 72 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero terminated. 
26410 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
26420 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
26430 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
26440 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
26450 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
26460 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
26470 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
26480 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
26490 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
264a0 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
264b0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
264c0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
264d0 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
264e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
264f0 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
26500 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
26510 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
26520 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
26530 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
26540 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
26550 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
26560 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
26570 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
26580 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
26590 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
265a0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
265b0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
265c0 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
265d0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
265e0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
265f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
26600 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
26610 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
26620 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
26630 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
26640 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
26650 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
26660 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
26670 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
26680 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
26690 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
266a0 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
266b0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
266c0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
266d0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
266e0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
266f0 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
26700 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
26710 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
26720 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
26730 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
26740 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
26750 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
26760 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
26770 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
26780 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
26790 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
267a0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
267b0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
267c0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
267d0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
267e0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
267f0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
26800 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
26810 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
26820 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
26830 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
26840 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
26850 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
26860 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
26870 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
26880 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
26890 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
268a0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
268b0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
268c0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
268d0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
268e0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
268f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
26900 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
26910 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
26920 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
26930 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
26940 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
26950 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
26960 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
26970 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
26980 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
26990 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
269a0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
269b0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
269c0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
269d0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
269e0 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
269f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
26a00 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
26a10 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
26a20 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
26a30 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
26a40 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
26a50 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
26a60 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
26a70 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
26a80 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
26a90 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
26aa0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
26ab0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
26ac0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
26ad0 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
26ae0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
26af0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
26b00 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
26b10 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
26b20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
26b30 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
26b40 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
26b50 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
26b60 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
26b70 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
26b80 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
26b90 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
26ba0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
26bb0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
26bc0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
26bd0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
26be0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
26bf0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
26c00 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
26c10 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
26c20 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
26c30 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
26c40 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
26c50 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
26c60 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
26c70 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
26c80 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
26c90 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
26ca0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
26cb0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
26cc0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
26cd0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
26ce0 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
26cf0 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
26d00 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
26d10 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
26d20 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
26d30 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
26d40 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
26d50 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
26d60 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
26d70 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
26d80 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
26d90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
26da0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
26db0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
26dc0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
26dd0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
26de0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
26df0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
26e00 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
26e10 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
26e20 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
26e30 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
26e40 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
26e50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
26e60 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
26e70 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
26e80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
26e90 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
26ea0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
26eb0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
26ec0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
26ed0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
26ee0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
26ef0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
26f00 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
26f10 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
26f20 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
26f30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
26f40 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
26f50 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
26f60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
26f70 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
26f80 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
26f90 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
26fa0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
26fb0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
26fc0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
26fd0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
26fe0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
26ff0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
27000 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
27010 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
27020 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
27030 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
27040 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
27050 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
27060 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
27070 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
27080 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
27090 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
270a0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
270b0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
270c0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
270d0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
270e0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
270f0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
27100 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
27110 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
27120 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
27130 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
27140 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
27150 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
27160 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
27170 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
27180 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
27190 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
271a0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
271b0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
271c0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
271d0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
271e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
271f0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
27200 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
27210 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
27220 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
27230 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
27240 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
27250 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
27260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27270 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
27280 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
27290 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
272a0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
272b0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
272c0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
272d0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
272e0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
272f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
27300 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
27310 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27320 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
27330 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
27340 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
27350 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
27360 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
27370 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
27380 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
27390 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
273a0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
273b0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
273c0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
273d0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
273e0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
273f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
27400 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
27410 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
27420 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
27430 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
27440 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
27450 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
27460 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
27470 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
27480 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
27490 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
274a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
274b0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
274c0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
274d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
274e0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
274f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
27500 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
27510 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
27520 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
27530 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
27540 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
27550 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
27560 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
27570 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
27580 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
27590 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
275a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
275b0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
275c0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
275d0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
275e0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
275f0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
27600 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
27610 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
27620 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
27630 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
27640 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
27650 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
27660 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
27670 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
27680 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
27690 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
276a0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
276b0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
276c0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
276d0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
276e0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
276f0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
27700 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
27710 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
27720 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
27730 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
27740 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
27750 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
27760 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
27770 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
27780 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
27790 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
277a0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
277b0 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
277c0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
277d0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
277e0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
277f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
27800 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
27810 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
27820 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
27830 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
27840 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27850 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
27860 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
27870 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
27880 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
27890 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
278a0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
278b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
278c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
278d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
278e0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
278f0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
27900 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
27910 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27920 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
27930 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
27940 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
27950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
27960 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
27970 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
27980 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27990 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
279a0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
279b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
279c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
279d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
279e0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
279f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
27a00 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
27a10 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
27a20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
27a30 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
27a40 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
27a50 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
27a60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27a70 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
27a80 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
27a90 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
27aa0 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
27ab0 65 64 20 6e 6f 20 65 72 72 6f 72 73 20 6f 72 0a  ed no errors or.
27ac0 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
27ad0 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
27ae0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
27af0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
27b00 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
27b10 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
27b20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
27b30 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
27b40 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
27b50 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
27b60 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
27b70 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
27b80 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
27b90 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
27ba0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
27bb0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
27bc0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
27bd0 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
27be0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
27bf0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
27c00 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
27c10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27c20 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
27c30 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
27c40 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
27c50 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
27c60 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
27c70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27c80 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
27c90 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
27ca0 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
27cb0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
27cc0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
27cd0 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
27ce0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
27cf0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
27d00 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
27d10 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
27d20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
27d30 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
27d40 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
27d50 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
27d60 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
27d70 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
27d80 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
27d90 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
27da0 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
27db0 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
27dc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
27dd0 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
27de0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27df0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
27e00 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
27e10 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
27e20 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
27e30 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
27e40 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
27e50 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
27e60 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
27e70 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
27e80 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
27e90 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
27ea0 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e  orruption..*/.in
27eb0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
27ec0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
27ed0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
27ee0 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
27ef0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
27f00 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
27f10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
27f20 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
27f30 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
27f40 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
27f50 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
27f60 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
27f70 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
27f80 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
27f90 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
27fa0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
27fb0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
27fc0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
27fd0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
27fe0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
27ff0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
28000 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
28010 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
28020 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
28030 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
28040 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
28050 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
28060 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
28070 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
28080 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
28090 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
280a0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
280b0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
280c0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
280d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
280e0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
280f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
28100 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
28110 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28120 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
28130 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
28140 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
28150 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
28160 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
28170 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
28180 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
28190 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
281a0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
281b0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
281c0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
281d0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
281e0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
281f0 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
28200 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
28210 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
28220 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
28230 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
28240 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
28250 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
28260 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
28270 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
28280 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
28290 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
282a0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
282b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
282c0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
282d0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
282e0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
282f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
28300 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
28310 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
28320 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
28330 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
28340 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
28350 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
28360 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
28370 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
28380 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
28390 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
283a0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
283b0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
283c0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
283d0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
283e0 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
283f0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
28400 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
28410 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
28420 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
28430 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
28440 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
28450 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
28460 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
28470 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
28480 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
28490 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
284a0 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
284b0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
284c0 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
284d0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
284e0 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
284f0 65 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  e the second par
28500 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
28510 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
28520 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
28530 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
28540 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
28550 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
28560 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
28570 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
28580 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
28590 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
285a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
285b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
285c0 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
285d0 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
285e0 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
285f0 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
28600 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
28610 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
28620 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
28630 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
28640 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
28650 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
28660 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
28670 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
28680 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
28690 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
286a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
286b0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
286c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
286d0 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
286e0 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
286f0 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
28700 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
28710 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
28720 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
28730 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
28740 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
28750 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
28760 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
28770 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
28780 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
28790 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
287a0 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
287b0 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
287c0 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
287d0 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
287e0 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
287f0 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
28800 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
28810 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
28820 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
28830 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
28840 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
28850 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
28860 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
28870 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
28880 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
28890 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
288a0 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
288b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
288c0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
288d0 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
288e0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
288f0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
28900 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
28910 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
28920 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
28930 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
28940 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
28950 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
28960 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
28970 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
28980 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
28990 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
289a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
289b0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
289c0 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
289d0 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
289e0 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
289f0 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
28a00 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
28a10 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
28a20 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20  ameters.  Every 
28a30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
28a40 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
28a50 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b   be able to work
28a60 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20  .** with UTF-8, 
28a70 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46  UTF-16le, or UTF
28a80 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65  -16be.  But some
28a90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
28aa0 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20   may be.** more 
28ab0 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f  efficient with o
28ac0 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e  ne encoding than
28ad0 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61   another.  ^An a
28ae0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a  pplication may.*
28af0 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
28b00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
28b10 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  () or sqlite3_cr
28b20 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
28b30 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69  ) multiple.** ti
28b40 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d  mes with the sam
28b50 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77  e function but w
28b60 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61  ith different va
28b70 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70  lues of eTextRep
28b80 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
28b90 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
28ba0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
28bb0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
28bc0 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
28bd0 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
28be0 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
28bf0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
28c00 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
28c10 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  rsion..** If the
28c20 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e  re is only a sin
28c30 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  gle implementati
28c40 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f  on which does no
28c50 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74  t care what text
28c60 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  .** encoding is 
28c70 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66  used, then the f
28c80 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73  ourth argument s
28c90 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45  hould be [SQLITE
28ca0 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  _ANY]..**.** ^(T
28cb0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
28cc0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
28cd0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
28ce0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28cf0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
28d00 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
28d10 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
28d20 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
28d30 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
28d40 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
28d50 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
28d60 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
28d70 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
28d80 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
28d90 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
28da0 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
28db0 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
28dc0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
28dd0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
28de0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
28df0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
28e00 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
28e10 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
28e20 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
28e30 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
28e40 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
28e50 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
28e60 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
28e70 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
28e80 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
28e90 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
28ea0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
28eb0 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
28ec0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
28ed0 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
28ee0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
28ef0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
28f00 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
28f10 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
28f20 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
28f30 20 70 6f 69 6e 65 72 73 20 66 6f 72 20 61 6c 6c   poiners for all
28f40 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
28f50 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
28f60 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
28f70 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
28f80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28f90 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
28fa0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
28fb0 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
28fc0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
28fd0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
28fe0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
28ff0 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
29000 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
29010 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
29020 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
29030 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
29040 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
29050 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
29060 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
29070 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
29080 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
29090 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
290a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
290b0 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
290c0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
290d0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
290e0 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
290f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
29100 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
29110 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
29120 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
29130 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
29140 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
29150 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
29160 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
29170 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
29180 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
29190 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
291a0 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
291b0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
291c0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
291d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
291e0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
291f0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
29200 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
29210 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
29220 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
29230 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
29240 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
29250 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
29260 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
29270 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
29280 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
29290 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
292a0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
292b0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
292c0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
292d0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
292e0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
292f0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
29300 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
29310 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
29320 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
29330 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
29340 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
29350 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
29360 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
29370 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
29380 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
29390 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
293a0 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
293b0 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
293c0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
293d0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
293e0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
293f0 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
29400 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
29410 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
29420 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
29430 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
29440 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
29450 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
29460 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
29470 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
29480 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
29490 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
294a0 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
294b0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
294c0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
294d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
294e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
294f0 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
29500 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
29510 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
29520 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
29530 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
29540 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
29550 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
29560 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
29570 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
29580 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
29590 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
295a0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
295b0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
295c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
295d0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
295e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
295f0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
29600 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
29610 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
29620 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
29630 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
29640 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
29650 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
29660 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
29670 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
29680 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
29690 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
296a0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
296b0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
296c0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
296d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
296e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
296f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
29700 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
29710 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
29720 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
29730 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
29740 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
29750 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
29760 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
29770 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
29780 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
29790 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
297a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
297b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
297c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
297d0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
297e0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
297f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
29800 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
29810 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
29820 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
29830 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
29840 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
29850 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
29860 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
29870 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29880 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
29890 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
298a0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
298b0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
298c0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
298d0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
298e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
298f0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
29900 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
29910 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29920 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
29930 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
29940 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
29950 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
29960 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
29970 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
29980 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
29990 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
299a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
299b0 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
299c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
299d0 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
299e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
299f0 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
29a00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
29a10 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
29a20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
29a30 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
29a40 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
29a50 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
29a60 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
29a70 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20  e_function only 
29a80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
29a90 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
29aa0 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
29ab0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
29ac0 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
29ad0 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
29ae0 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
29af0 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
29b00 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
29b10 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
29b20 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
29b30 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
29b40 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
29b50 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
29b60 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
29b70 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
29b80 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
29b90 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
29ba0 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
29bb0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
29bc0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
29bd0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
29be0 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20   help encourage 
29bf0 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a  people to avoid.
29c00 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66  ** using these f
29c10 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65  unctions, we are
29c20 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65   not going to te
29c30 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79  ll you what they
29c40 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
29c50 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
29c60 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45  ECATED.SQLITE_DE
29c70 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
29c80 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
29c90 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
29ca0 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  text*);.SQLITE_D
29cb0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
29cc0 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
29cd0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
29ce0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
29cf0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
29d00 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
29d10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
29d20 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
29d30 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
29d40 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
29d50 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
29d60 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
29d70 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
29d80 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
29d90 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
29da0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
29db0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
29dc0 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
29dd0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
29de0 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
29df0 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
29e00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29e10 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
29e20 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
29e30 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
29e40 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
29e50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
29e60 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
29e70 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
29e80 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
29e90 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
29ea0 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
29eb0 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
29ec0 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
29ed0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
29ee0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
29ef0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
29f00 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
29f10 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
29f20 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
29f30 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
29f40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
29f50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
29f60 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
29f70 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
29f80 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
29f90 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
29fa0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
29fb0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
29fc0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
29fd0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
29fe0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
29ff0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
2a000 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2a010 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2a020 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
2a030 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2a040 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
2a050 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2a060 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
2a070 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
2a080 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
2a090 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
2a0a0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
2a0b0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2a0c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2a0d0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
2a0e0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
2a0f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2a100 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
2a110 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
2a120 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
2a130 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
2a140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
2a150 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
2a160 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
2a170 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
2a180 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2a190 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
2a1a0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
2a1b0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2a1c0 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
2a1d0 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
2a1e0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
2a1f0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
2a200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2a210 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
2a220 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
2a230 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
2a240 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
2a250 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
2a260 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
2a270 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2a280 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
2a290 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
2a2a0 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
2a2b0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
2a2c0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
2a2d0 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
2a2e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2a2f0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
2a300 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2a310 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
2a320 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
2a330 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
2a340 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
2a350 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
2a360 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
2a370 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
2a380 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
2a390 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
2a3a0 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
2a3b0 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
2a3c0 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
2a3d0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
2a3e0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
2a3f0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
2a400 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
2a410 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
2a420 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
2a430 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
2a440 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
2a450 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
2a460 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
2a470 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
2a480 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
2a490 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
2a4a0 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
2a4b0 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
2a4c0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
2a4d0 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
2a4e0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
2a4f0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
2a500 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
2a510 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
2a520 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
2a530 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
2a540 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
2a550 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
2a560 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
2a570 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
2a580 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
2a590 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
2a5a0 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
2a5b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2a5c0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
2a5d0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2a5e0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
2a5f0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
2a600 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
2a610 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2a620 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
2a630 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2a640 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
2a650 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
2a660 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
2a670 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
2a680 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2a690 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
2a6a0 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2a6b0 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
2a6c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
2a6d0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
2a6e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
2a6f0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
2a700 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2a710 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2a720 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2a730 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
2a740 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  ue_bytes(sqlite3
2a750 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2a760 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2a770 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  s16(sqlite3_valu
2a780 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69  e*);.double sqli
2a790 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65  te3_value_double
2a7a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2a7b0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2a7c0 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  lue_int(sqlite3_
2a7d0 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33  value*);.sqlite3
2a7e0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76  _int64 sqlite3_v
2a7f0 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74  alue_int64(sqlit
2a800 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
2a810 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
2a820 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2a830 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
2a840 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
2a850 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2a860 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61  ext16(sqlite3_va
2a870 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2a880 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2a890 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
2a8a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
2a8b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
2a8c0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71  alue_text16be(sq
2a8d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2a8e0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2a8f0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
2a900 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2a910 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
2a920 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61  _type(sqlite3_va
2a930 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  lue*);../*.** CA
2a940 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41  PI3REF: Obtain A
2a950 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f  ggregate Functio
2a960 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  n Context.**.** 
2a970 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
2a980 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
2a990 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
2a9a0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
2a9b0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
2a9c0 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
2a9d0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
2a9e0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
2a9f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
2aa00 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2aa10 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
2aa20 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
2aa30 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
2aa40 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
2aa50 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
2aa60 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
2aa70 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
2aa80 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
2aa90 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
2aaa0 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
2aab0 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
2aac0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
2aad0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
2aae0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2aaf0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
2ab00 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
2ab10 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
2ab20 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
2ab30 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
2ab40 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
2ab50 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
2ab60 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
2ab70 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
2ab80 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
2ab90 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
2aba0 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
2abb0 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
2abc0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
2abd0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
2abe0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
2abf0 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
2ac00 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
2ac10 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
2ac20 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
2ac30 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
2ac40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
2ac50 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
2ac60 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
2ac70 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
2ac80 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
2ac90 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
2aca0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2acb0 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
2acc0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
2acd0 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
2ace0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
2acf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ad00 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2ad10 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
2ad20 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
2ad30 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69  L pointer if N i
2ad40 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f  s.** less than o
2ad50 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
2ad60 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  or if a memory a
2ad70 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
2ad80 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
2ad90 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
2ada0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
2adb0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2adc0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
2add0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
2ade0 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
2adf0 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
2ae00 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
2ae10 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
2ae20 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
2ae30 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
2ae40 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2ae50 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
2ae60 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
2ae70 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
2ae80 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
2ae90 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
2aea0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
2aeb0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  n.)^.**.** ^SQLi
2aec0 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
2aed0 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
2aee0 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
2aef0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
2af00 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
2af10 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
2af20 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
2af30 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
2af40 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
2af50 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
2af60 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
2af70 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
2af80 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
2af90 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
2afa0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
2afb0 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
2afc0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
2afd0 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
2afe0 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
2aff0 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
2b000 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2b010 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2b020 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2b030 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2b040 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
2b050 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
2b060 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
2b070 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
2b080 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
2b090 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2b0a0 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
2b0b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
2b0c0 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
2b0d0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
2b0e0 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
2b0f0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
2b100 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
2b110 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
2b120 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
2b130 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
2b140 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
2b150 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
2b160 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b170 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
2b180 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2b190 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2b1a0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
2b1b0 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
2b1c0 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
2b1d0 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2b1e0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
2b1f0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
2b200 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2b210 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2b220 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2b230 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b240 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
2b250 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
2b260 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
2b270 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
2b280 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
2b290 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
2b2a0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
2b2b0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
2b2c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ^The sqlite3_con
2b2d0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
2b2e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b2f0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
2b300 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
2b310 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
2b320 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
2b330 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
2b340 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2b350 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2b360 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2b370 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2b380 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
2b390 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
2b3a0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
2b3b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2b3c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2b3d0 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c  .*/.sqlite3 *sql
2b3e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2b3f0 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
2b400 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
2b410 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
2b420 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
2b430 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  ta.**.** The fol
2b440 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
2b450 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
2b460 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
2b470 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
2b480 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
2b490 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
2b4a0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
2b4b0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
2b4c0 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
2b4d0 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
2b4e0 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
2b4f0 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
2b500 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
2b510 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
2b520 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
2b530 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
2b540 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
2b550 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a  rved. This may.*
2b560 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  * be used, for e
2b570 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61  xample, to add a
2b580 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
2b590 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61  ion matching sca
2b5a0 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  lar.** function.
2b5b0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
2b5c0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
2b5d0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2b5e0 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  is stored as.** 
2b5f0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
2b600 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
2b610 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
2b620 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2b630 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
2b640 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
2b650 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
2b660 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
2b670 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
2b680 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
2b690 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2b6a0 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
2b6b0 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
2b6c0 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
2b6d0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
2b6e0 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
2b6f0 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
2b700 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b710 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
2b720 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2b730 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2b740 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
2b750 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
2b760 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2b770 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
2b780 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
2b790 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
2b7a0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2b7b0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2b7c0 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  . ^If no metadat
2b7d0 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
2b7e0 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
2b7f0 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
2b800 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2b810 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
2b820 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
2b830 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
2b840 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
2b850 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
2b860 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
2b870 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2b880 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
2b890 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2b8a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b8b0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2b8c0 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
2b8d0 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
2b8e0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
2b8f0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
2b900 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  as the metadata 
2b910 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
2b920 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
2b930 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2b940 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
2b950 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2b960 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
2b970 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
2b980 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
2b990 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
2b9a0 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
2b9b0 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  yed..** ^If it i
2b9c0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
2b9d0 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
2b9e0 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2b9f0 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
2ba00 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
2ba10 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2ba20 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
2ba30 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61  .** the metadata
2ba40 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
2ba50 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
2ba60 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
2ba70 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
2ba80 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2ba90 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
2baa0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
2bab0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
2bac0 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74  s free to call t
2bad0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e  he destructor an
2bae0 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20  d drop metadata 
2baf0 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65  on any.** parame
2bb00 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74  ter of any funct
2bb10 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e  ion at any time.
2bb20 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72    ^The only guar
2bb30 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a  antee is that.**
2bb40 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2bb50 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  will be called b
2bb60 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61  efore the metada
2bb70 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a  ta is dropped..*
2bb80 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
2bb90 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
2bba0 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
2bbb0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
2bbc0 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
2bbd0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
2bbe0 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
2bbf0 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
2bc00 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
2bc10 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61  values and [para
2bc20 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  meters].)^.**.**
2bc30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2bc40 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2bc50 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2bc60 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2bc70 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2bc80 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
2bc90 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
2bca0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
2bcb0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2bcc0 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  N);.void sqlite3
2bcd0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
2bce0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2bcf0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
2bd00 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
2bd10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2bd20 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
2bd30 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
2bd40 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
2bd50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
2bd60 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
2bd70 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
2bd80 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
2bd90 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
2bda0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
2bdb0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2bdc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2bdd0 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
2bde0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
2bdf0 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
2be00 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
2be10 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2be20 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
2be30 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
2be40 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
2be50 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
2be60 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
2be70 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
2be80 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
2be90 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
2bea0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
2beb0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
2bec0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
2bed0 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
2bee0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
2bef0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2bf00 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
2bf10 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
2bf20 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
2bf30 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
2bf40 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
2bf50 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
2bf60 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
2bf70 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
2bf80 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
2bf90 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
2bfa0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
2bfb0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
2bfc0 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
2bfd0 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
2bfe0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2bff0 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
2c000 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
2c010 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
2c020 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2c030 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
2c040 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
2c050 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
2c060 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
2c070 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2c080 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
2c090 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
2c0a0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
2c0b0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
2c0c0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2c0d0 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
2c0e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2c0f0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2c100 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2c110 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2c120 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
2c130 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
2c140 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2c150 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
2c160 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
2c170 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
2c180 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
2c190 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
2c1a0 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
2c1b0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
2c1c0 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
2c1d0 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
2c1e0 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
2c1f0 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
2c200 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
2c210 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
2c220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c230 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2c240 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2c250 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
2c260 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
2c270 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2c280 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
2c290 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
2c2a0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
2c2b0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
2c2c0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
2c2d0 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
2c2e0 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
2c2f0 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
2c300 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
2c310 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2c320 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
2c330 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
2c340 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2c350 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2c360 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2c370 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
2c380 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
2c390 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
2c3a0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
2c3b0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
2c3c0 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
2c3d0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
2c3e0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2c3f0 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
2c400 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2c410 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
2c420 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2c430 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2c440 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
2c450 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
2c460 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
2c470 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2c480 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2c490 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
2c4a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c4b0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
2c4c0 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
2c4d0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
2c4e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
2c4f0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
2c500 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2c510 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
2c520 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
2c530 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
2c540 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
2c550 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
2c560 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2c570 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
2c580 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
2c590 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
2c5a0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
2c5b0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2c5c0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
2c5d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2c5e0 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
2c5f0 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
2c600 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
2c610 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2c620 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
2c630 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
2c640 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
2c650 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
2c660 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2c670 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c680 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
2c690 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2c6a0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
2c6b0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
2c6c0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
2c6d0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
2c6e0 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
2c6f0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
2c700 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
2c710 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2c720 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
2c730 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
2c740 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2c750 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
2c760 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
2c770 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
2c780 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
2c790 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
2c7a0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
2c7b0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
2c7c0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
2c7d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2c7e0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
2c7f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c800 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
2c810 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
2c820 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
2c830 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
2c840 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
2c850 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
2c860 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
2c870 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
2c880 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
2c890 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
2c8a0 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
2c8b0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
2c8c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2c8d0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
2c8e0 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
2c8f0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
2c900 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2c910 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
2c920 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
2c930 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
2c940 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
2c950 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
2c960 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
2c970 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
2c980 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
2c990 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
2c9a0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2c9b0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
2c9c0 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
2c9d0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
2c9e0 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
2c9f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
2ca00 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
2ca10 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2ca20 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
2ca30 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
2ca40 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
2ca50 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
2ca60 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
2ca70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ca80 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
2ca90 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2caa0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
2cab0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
2cac0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
2cad0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2cae0 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
2caf0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2cb00 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
2cb10 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2cb20 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2cb30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2cb40 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2cb50 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
2cb60 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2cb70 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
2cb80 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
2cb90 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
2cba0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2cbb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2cbc0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2cbd0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2cbe0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2cbf0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2cc00 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
2cc10 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
2cc20 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
2cc30 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2cc40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2cc50 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
2cc60 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2cc70 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2cc80 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2cc90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2cca0 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
2ccb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2ccc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2ccd0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
2cce0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
2ccf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2cd00 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
2cd10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2cd20 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
2cd30 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
2cd40 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2cd50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2cd60 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2cd70 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
2cd80 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
2cd90 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
2cda0 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
2cdb0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
2cdc0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
2cdd0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
2cde0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
2cdf0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2ce00 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
2ce10 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
2ce20 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
2ce30 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
2ce40 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
2ce50 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2ce60 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2ce70 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
2ce80 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
2ce90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2cea0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2ceb0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
2cec0 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
2ced0 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
2cee0 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
2cef0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
2cf00 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2cf10 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2cf20 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
2cf30 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2cf40 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2cf50 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2cf60 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
2cf70 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
2cf80 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
2cf90 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
2cfa0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
2cfb0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2cfc0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
2cfd0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
2cfe0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
2cff0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
2d000 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
2d010 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2d020 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2d030 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2d040 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
2d050 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
2d060 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
2d070 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
2d080 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
2d090 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
2d0a0 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
2d0b0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
2d0c0 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
2d0d0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
2d0e0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
2d0f0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2d100 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2d110 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2d120 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
2d130 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2d140 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
2d150 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
2d160 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
2d170 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
2d180 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
2d190 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
2d1a0 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
2d1b0 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
2d1c0 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
2d1d0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2d1e0 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
2d1f0 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
2d200 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
2d210 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
2d220 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
2d230 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
2d240 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2d250 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2d260 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2d270 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
2d280 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2d290 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
2d2a0 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
2d2b0 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
2d2c0 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
2d2d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2d2e0 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
2d2f0 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
2d300 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2d310 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
2d320 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
2d330 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d340 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2d350 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2d360 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
2d370 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2d380 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2d390 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
2d3a0 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
2d3b0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2d3c0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
2d3d0 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
2d3e0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
2d3f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d400 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
2d410 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
2d420 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
2d430 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
2d440 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2d450 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
2d460 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
2d470 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
2d480 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2d490 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
2d4a0 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
2d4b0 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
2d4c0 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
2d4d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2d4e0 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
2d4f0 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
2d500 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
2d510 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d520 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
2d530 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
2d540 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
2d550 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d560 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
2d570 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
2d580 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
2d590 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2d5a0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
2d5b0 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
2d5c0 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
2d5d0 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
2d5e0 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
2d5f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2d600 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
2d610 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
2d620 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
2d630 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
2d640 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2d650 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
2d660 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c  _result_blob(sql
2d670 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
2d680 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2d690 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2d6a0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d6b0 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c  esult_double(sql
2d6c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64  ite3_context*, d
2d6d0 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c  ouble);.void sql
2d6e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2d6f0 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
2d700 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
2d710 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69   int);.void sqli
2d720 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2d730 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
2d740 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2d750 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c  , int);.void sql
2d760 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2d770 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33  r_toobig(sqlite3
2d780 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
2d790 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d7a0 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69  error_nomem(sqli
2d7b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
2d7c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2d7d0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
2d7e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d7f0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2d800 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71  e3_result_int(sq
2d810 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2d820 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
2d830 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
2d840 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d850 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
2d860 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
2d870 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74  esult_null(sqlit
2d880 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f  e3_context*);.vo
2d890 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d8a0 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  t_text(sqlite3_c
2d8b0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
2d8c0 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  har*, int, void(
2d8d0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2d8e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d8f0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 63  text16(sqlite3_c
2d900 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
2d910 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
2d920 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
2d930 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d940 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
2d950 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2d960 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
2d970 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69  (*)(void*));.voi
2d980 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2d990 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2d9a0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2d9b0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
2d9c0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
2d9d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d9e0 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  t_value(sqlite3_
2d9f0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
2da00 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
2da10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
2da20 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2da30 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
2da40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2da50 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
2da60 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
2da70 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  s.**.** ^These f
2da80 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
2da90 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
2daa0 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
2dab0 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2dac0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2dad0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
2dae0 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
2daf0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
2db00 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2db10 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
2db20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
2db30 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
2db40 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2db50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
2db60 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2db70 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
2db80 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
2db90 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
2dba0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2dbb0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
2dbc0 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
2dbd0 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
2dbe0 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
2dbf0 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
2dc00 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
2dc10 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
2dc20 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
2dc30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
2dc40 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
2dc50 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
2dc60 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
2dc70 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
2dc80 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
2dc90 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
2dca0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
2dcb0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
2dcc0 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
2dcd0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2dce0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
2dcf0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
2dd00 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
2dd10 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
2dd20 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
2dd30 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
2dd40 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
2dd50 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
2dd60 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
2dd70 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
2dd80 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
2dd90 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
2dda0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2ddb0 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
2ddc0 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
2ddd0 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
2dde0 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
2ddf0 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
2de00 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
2de10 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
2de20 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
2de30 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
2de40 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
2de50 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
2de60 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
2de70 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
2de80 20 70 41 72 67 2c 20 69 73 20 61 20 61 70 70 6c   pArg, is a appl
2de90 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2dea0 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
2deb0 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  sed.** through a
2dec0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
2ded0 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c  ment to the coll
2dee0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
2def0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
2df00 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
2df10 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69  nt, xCallback, i
2df20 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2df30 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2df40 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69  ction..** ^Multi
2df50 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ple collating fu
2df60 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72  nctions can be r
2df70 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2df80 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
2df90 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72  t.** with differ
2dfa0 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72  ent eTextRep par
2dfb0 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69  ameters and SQLi
2dfc0 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63  te will use whic
2dfd0 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  hever.** functio
2dfe0 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c  n requires the l
2dff0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
2e000 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69  ata transformati
2e010 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78  on..** ^If the x
2e020 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  Callback argumen
2e030 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  t is NULL then t
2e040 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2e050 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65  ction is.** dele
2e060 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20  ted.  ^When all 
2e070 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2e080 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73  ons having the s
2e090 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c  ame name are del
2e0a0 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f  eted,.** that co
2e0b0 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f  llation is no lo
2e0c0 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a  nger usable..**.
2e0d0 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e  ** ^The collatin
2e0e0 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
2e0f0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
2e100 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ith a copy of th
2e110 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69  e pArg .** appli
2e120 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2e130 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f  ter and with two
2e140 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
2e150 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2e160 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65  ed.** by the eTe
2e170 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20  xtRep argument. 
2e180 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
2e190 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74  unction must ret
2e1a0 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65  urn an.** intege
2e1b0 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69  r that is negati
2e1c0 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73  ve, zero, or pos
2e1d0 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20  itive.** if the 
2e1e0 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
2e1f0 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
2e200 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
2e210 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c  than the second,
2e220 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2e230 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  .  A collating f
2e240 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77  unction must alw
2e250 61 79 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ay return the sa
2e260 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
2e270 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
2e280 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
2e290 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
2e2a0 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
2e2b0 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
2e2c0 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
2e2d0 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
2e2e0 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
2e2f0 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
2e300 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
2e310 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
2e320 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
2e330 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
2e340 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
2e350 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2e360 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
2e370 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
2e380 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
2e390 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
2e3a0 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
2e3b0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
2e3c0 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
2e3d0 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
2e3e0 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
2e3f0 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
2e400 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
2e410 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
2e420 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
2e430 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
2e440 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
2e450 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
2e460 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
2e470 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
2e480 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
2e490 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2e4a0 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
2e4b0 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
2e4c0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
2e4d0 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
2e4e0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2e4f0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2e500 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
2e510 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
2e520 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e530 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
2e540 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
2e550 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
2e560 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
2e570 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
2e580 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
2e590 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
2e5a0 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
2e5b0 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
2e5c0 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
2e5d0 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
2e5e0 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
2e5f0 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
2e600 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
2e610 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
2e620 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
2e630 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
2e640 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
2e650 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
2e660 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
2e670 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
2e680 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
2e690 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
2e6a0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e6b0 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
2e6c0 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
2e6d0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
2e6e0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
2e6f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2e700 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
2e710 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
2e720 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
2e730 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
2e740 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
2e750 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
2e760 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2e770 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
2e780 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
2e790 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
2e7a0 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
2e7b0 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
2e7c0 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
2e7d0 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
2e7e0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
2e7f0 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
2e800 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
2e810 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
2e820 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
2e830 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
2e840 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
2e850 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
2e860 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
2e870 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2e880 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
2e890 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2e8a0 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
2e8b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
2e8c0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
2e8d0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
2e8e0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
2e8f0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2e900 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
2e910 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
2e920 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
2e930 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
2e940 20 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73   void*).);.int s
2e950 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2e960 6c 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  llation_v2(.  sq
2e970 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2e980 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
2e990 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
2e9a0 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
2e9b0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
2e9c0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2e9d0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
2e9e0 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  oid*),.  void(*x
2e9f0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
2ea00 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2ea10 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
2ea20 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
2ea30 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e    const void *zN
2ea40 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  ame,.  int eText
2ea50 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
2ea60 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
2ea70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2ea80 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2ea90 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
2eaa0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2eab0 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64  Collation Needed
2eac0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
2ead0 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e   ^To avoid havin
2eae0 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c  g to register al
2eaf0 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  l collation sequ
2eb00 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64  ences before a d
2eb10 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62  atabase.** can b
2eb20 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65  e used, a single
2eb30 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
2eb40 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
2eb50 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  ered with the.**
2eb60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2eb70 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76  ction] to be inv
2eb80 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
2eb90 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61   undefined colla
2eba0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
2ebb0 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a   is required..**
2ebc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63  .** ^If the func
2ebd0 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72  tion is register
2ebe0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  ed using the sql
2ebf0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2ec00 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20  eeded() API,.** 
2ec10 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65  then it is passe
2ec20 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75  d the names of u
2ec30 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69  ndefined collati
2ec40 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20  on sequences as 
2ec50 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64  strings.** encod
2ec60 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66  ed in UTF-8. ^If
2ec70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
2ec80 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73  on_needed16() is
2ec90 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61   used,.** the na
2eca0 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61  mes are passed a
2ecb0 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68  s UTF-16 in mach
2ecc0 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  ine native byte 
2ecd0 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c  order..** ^A cal
2ece0 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63  l to either func
2ecf0 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68  tion replaces th
2ed00 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61  e existing colla
2ed10 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c  tion-needed call
2ed20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68  back..**.** ^(Wh
2ed30 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
2ed40 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20  is invoked, the 
2ed50 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70  first argument p
2ed60 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a  assed is a copy.
2ed70 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ** of the second
2ed80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2ed90 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2eda0 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71  eeded() or.** sq
2edb0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2edc0 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65  needed16().  The
2edd0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2ede0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
2edf0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
2ee00 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
2ee10 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  ent is one of [S
2ee20 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2ee30 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a  LITE_UTF16BE],.*
2ee40 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  * or [SQLITE_UTF
2ee50 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e  16LE], indicatin
2ee60 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72  g the most desir
2ee70 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65  able form of the
2ee80 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65   collation.** se
2ee90 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20  quence function 
2eea0 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66  required.  The f
2eeb0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2eec0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
2eed0 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63  he.** required c
2eee0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
2eef0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  e.)^.**.** The c
2ef00 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2ef10 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72   should register
2ef20 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
2ef30 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  lation using.** 
2ef40 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2ef50 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73  collation()], [s
2ef60 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2ef70 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  llation16()], or
2ef80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
2ef90 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2efa0 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
2efb0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
2efc0 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a  eded(.  sqlite3*
2efd0 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76  , .  void*, .  v
2efe0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
2eff0 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52  ite3*,int eTextR
2f000 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a  ep,const char*).
2f010 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2f020 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2f030 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  6(.  sqlite3*, .
2f040 20 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28    void*,.  void(
2f050 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2f060 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2f070 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a  onst void*).);..
2f080 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41  #ifdef SQLITE_HA
2f090 53 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70  S_CODEC./*.** Sp
2f0a0 65 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f  ecify the key fo
2f0b0 72 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64  r an encrypted d
2f0c0 61 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72  atabase.  This r
2f0d0 6f 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65  outine should be
2f0e0 0a 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74  .** called right
2f0f0 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f   after sqlite3_o
2f100 70 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  pen()..**.** The
2f110 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
2f120 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
2f130 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
2f140 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
2f150 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
2f160 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f170 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
2f180 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
2f190 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2f1a0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
2f1b0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2f1c0 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
2f1d0 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a      /* The key *
2f1e0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e  /.);../*.** Chan
2f1f0 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e  ge the key on an
2f200 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20   open database. 
2f210 20 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20   If the current 
2f220 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a  database is not.
2f230 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68  ** encrypted, th
2f240 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
2f250 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20  encrypt it.  If 
2f260 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d  pNew==0 or nNew=
2f270 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  =0, the.** datab
2f280 61 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64  ase is decrypted
2f290 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
2f2a0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
2f2b0 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
2f2c0 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
2f2d0 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
2f2e0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
2f2f0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
2f300 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2f310 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f320 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
2f330 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
2f340 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
2f350 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
2f360 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
2f370 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
2f380 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
2f390 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
2f3a0 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
2f3b0 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
2f3c0 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
2f3d0 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
2f3e0 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
2f3f0 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
2f400 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
2f410 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
2f420 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
2f430 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
2f440 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
2f450 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
2f460 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
2f470 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
2f480 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
2f490 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
2f4a0 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
2f4b0 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
2f4c0 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
2f4d0 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
2f4e0 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
2f4f0 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
2f500 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
2f510 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
2f520 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
2f530 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
2f540 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
2f550 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
2f560 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
2f570 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2f580 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
2f590 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
2f5a0 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
2f5b0 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
2f5c0 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
2f5d0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
2f5e0 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
2f5f0 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
2f600 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
2f610 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
2f620 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
2f630 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
2f640 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
2f650 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
2f660 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
2f670 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
2f680 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
2f690 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
2f6a0 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
2f6b0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
2f6c0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
2f6d0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
2f6e0 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
2f6f0 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
2f700 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
2f710 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
2f720 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
2f730 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
2f740 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
2f750 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
2f760 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
2f770 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65  ct.  If the xSle
2f780 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  ep() method.** o
2f790 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
2f7a0 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  S is not impleme
2f7b0 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20  nted correctly, 
2f7c0 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  or not implement
2f7d0 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68  ed at.** all, th
2f7e0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2f7f0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  of sqlite3_sleep
2f800 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66  () may deviate f
2f810 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74  rom the descript
2f820 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72  ion.** in the pr
2f830 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
2f840 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2f850 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
2f860 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2f870 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
2f880 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
2f890 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
2f8a0 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
2f8b0 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
2f8c0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
2f8d0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
2f8e0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
2f8f0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
2f900 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
2f910 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
2f920 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
2f930 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
2f940 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
2f950 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
2f960 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
2f970 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
2f980 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
2f990 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
2f9a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2f9b0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
2f9c0 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
2f9d0 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
2f9e0 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
2f9f0 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
2fa00 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ..**.** It is no
2fa10 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
2fa20 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
2fa30 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74  riable in more t
2fa40 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61  han one.** threa
2fa50 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74  d at a time.  It
2fa60 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
2fa70 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
2fa80 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  his variable.** 
2fa90 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  if a [database c
2faa0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
2fab0 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65 20  ing used at the 
2fac0 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73  same time in a s
2fad0 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61  eparate.** threa
2fae0 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65  d..** It is inte
2faf0 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20 76  nded that this v
2fb00 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f  ariable be set o
2fb10 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f  nce.** as part o
2fb20 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  f process initia
2fb30 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66  lization and bef
2fb40 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  ore any SQLite i
2fb50 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74  nterface.** rout
2fb60 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20 63  ines have been c
2fb70 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74  alled and that t
2fb80 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d  his variable rem
2fb90 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a  ain unchanged.**
2fba0 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a   thereafter..**.
2fbb0 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74  ** ^The [temp_st
2fbc0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2fbd0 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79  agma] may modify
2fbe0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 61   this variable a
2fbf0 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74  nd cause.** it t
2fc00 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
2fc10 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
2fc20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
2fc30 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c  .  ^Furthermore,
2fc40 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74  .** the [temp_st
2fc50 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2fc60 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73  agma] always ass
2fc70 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73 74  umes that any st
2fc80 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69  ring.** that thi
2fc90 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74  s variable point
2fca0 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20  s to is held in 
2fcb0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
2fcc0 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
2fcd0 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68  3_malloc] and th
2fce0 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74  e pragma may att
2fcf0 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68 61  empt to free tha
2fd00 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e  t memory.** usin
2fd10 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d  g [sqlite3_free]
2fd20 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74  ..** Hence, if t
2fd30 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73 20  his variable is 
2fd40 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74 6c  modified directl
2fd50 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68 6f  y, either it sho
2fd60 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e  uld be.** made N
2fd70 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70  ULL or made to p
2fd80 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f  oint to memory o
2fd90 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2fda0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a  lite3_malloc].**
2fdb0 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73 65   or else the use
2fdc0 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74   of the [temp_st
2fdd0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
2fde0 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20  agma] should be 
2fdf0 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  avoided..*/.SQLI
2fe00 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20 2a  TE_EXTERN char *
2fe10 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
2fe20 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ectory;../*.** C
2fe30 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46 6f  API3REF: Test Fo
2fe40 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d 6f  r Auto-Commit Mo
2fe50 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  de.** KEYWORDS: 
2fe60 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  {autocommit mode
2fe70 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  }.**.** ^The sql
2fe80 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
2fe90 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  mit() interface 
2fea0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
2feb0 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20 74   or.** zero if t
2fec0 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61 73  he given databas
2fed0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2fee0 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75 74  or is not in aut
2fef0 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a 2a  ocommit mode,.**
2ff00 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20   respectively.  
2ff10 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
2ff20 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75 6c   is on by defaul
2ff30 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69  t..** ^Autocommi
2ff40 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62 6c  t mode is disabl
2ff50 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d 20  ed by a [BEGIN] 
2ff60 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 41  statement..** ^A
2ff70 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69  utocommit mode i
2ff80 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79 20  s re-enabled by 
2ff90 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b 52  a [COMMIT] or [R
2ffa0 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  OLLBACK]..**.** 
2ffb0 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64 73  If certain kinds
2ffc0 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75 72   of errors occur
2ffd0 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74 20   on a statement 
2ffe0 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d 73  within a multi-s
2fff0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61 6e  tatement.** tran
30000 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73 20  saction (errors 
30010 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49 54  including [SQLIT
30020 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54 45  E_FULL], [SQLITE
30030 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  _IOERR],.** [SQL
30040 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51 4c  ITE_NOMEM], [SQL
30050 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20 5b  ITE_BUSY], and [
30060 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
30070 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 74  ]) then the.** t
30080 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68 74  ransaction might
30090 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
300a0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
300b0 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f 0a  The only way to.
300c0 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65 74  ** find out whet
300d0 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f 6d  her SQLite autom
300e0 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
300f0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
30100 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61 6e  tion after.** an
30110 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73 65   error is to use
30120 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
30130 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65 72  **.** If another
30140 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73 20   thread changes 
30150 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20 73  the autocommit s
30160 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61 74  tatus of the dat
30170 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
30180 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20 72  ion while this r
30190 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69 6e  outine is runnin
301a0 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  g, then the retu
301b0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 75  rn value.** is u
301c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74  ndefined..*/.int
301d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
301e0 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a  ocommit(sqlite3*
301f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30200 45 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74  EF: Find The Dat
30210 61 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20  abase Handle Of 
30220 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
30230 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ment.**.** ^The 
30240 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
30250 65 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  e interface retu
30260 72 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73  rns the [databas
30270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
30280 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68  ndle.** to which
30290 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
302a0 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e  tement] belongs.
302b0 20 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65    ^The [database
302c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20   connection].** 
302d0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
302e0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73  te3_db_handle is
302f0 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
30300 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
30310 2a 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20  ** that was the 
30320 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a  first argument.*
30330 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
30340 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
30350 63 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72  call (or its var
30360 69 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20  iants) that was 
30370 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74  used to.** creat
30380 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  e the statement 
30390 69 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61  in the first pla
303a0 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  ce..*/.sqlite3 *
303b0 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
303c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  e(sqlite3_stmt*)
303d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
303e0 46 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74  F: Find the next
303f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
30400 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ent.**.** ^This 
30410 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30420 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
30430 68 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65  he next [prepare
30440 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74  d statement] aft
30450 65 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f  er.** pStmt asso
30460 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
30470 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
30480 74 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20  tion] pDb.  ^If 
30490 70 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a  pStmt is NULL.**
304a0 20 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72   then this inter
304b0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
304c0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69  ointer to the fi
304d0 72 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61  rst prepared sta
304e0 74 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69  tement.** associ
304f0 61 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61  ated with the da
30500 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30510 6e 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70  n pDb.  ^If no p
30520 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30530 74 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74  t.** satisfies t
30540 68 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66  he conditions of
30550 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69   this routine, i
30560 74 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a  t returns NULL..
30570 2a 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62  **.** The [datab
30580 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
30590 70 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63  pointer D in a c
305a0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
305b0 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53  e3_next_stmt(D,S
305c0 29 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f  )] must refer to
305d0 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   an open databas
305e0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
305f0 61 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61  and in particula
30600 72 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20  r must not be a 
30610 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f  NULL pointer..*/
30620 0a 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73  .sqlite3_stmt *s
30630 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
30640 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73  (sqlite3 *pDb, s
30650 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
30660 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
30670 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64  3REF: Commit And
30680 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69   Rollback Notifi
30690 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
306a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
306b0 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
306c0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
306d0 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
306e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  .** function to 
306f0 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
30700 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ver a transactio
30710 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63  n is [COMMIT | c
30720 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41  ommitted]..** ^A
30730 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
30740 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
30750 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ll to sqlite3_co
30760 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66  mmit_hook().** f
30770 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
30780 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
30790 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
307a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
307b0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69  ollback_hook() i
307c0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
307d0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  rs a callback.**
307e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
307f0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
30800 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
30810 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f  s [ROLLBACK | ro
30820 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e  lled back]..** ^
30830 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
30840 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
30850 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
30860 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a  ollback_hook().*
30870 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64  * for the same d
30880 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30890 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e  on is overridden
308a0 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61  ..** ^The pArg a
308b0 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65  rgument is passe
308c0 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
308d0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49   callback..** ^I
308e0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f  f the callback o
308f0 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  n a commit hook 
30900 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
30910 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68   non-zero,.** th
30920 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73  en the commit is
30930 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
30940 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  a rollback..**.*
30950 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
30960 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50  ommit_hook(D,C,P
30970 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f  ) and sqlite3_ro
30980 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c  llback_hook(D,C,
30990 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  P) functions.** 
309a0 72 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67  return the P arg
309b0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
309c0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20  revious call of 
309d0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
309e0 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65  n.** on the same
309f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30a00 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c  ction] D, or NUL
30a10 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72  L for.** the fir
30a20 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68  st call for each
30a30 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a   function on D..
30a40 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
30a50 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ck implementatio
30a60 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  n must not do an
30a70 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
30a80 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
30a90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
30aa0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
30ab0 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20 41  the callback.  A
30ac0 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f  ny actions.** to
30ad0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
30ae0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
30af0 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64  must be deferred
30b00 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65   until after the
30b10 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f  .** completion o
30b20 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  f the [sqlite3_s
30b30 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74  tep()] call that
30b40 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20 63   triggered the c
30b50 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c  ommit.** or roll
30b60 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68 65  back hook in the
30b70 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2a   first place..**
30b80 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
30b90 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
30ba0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
30bb0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
30bc0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
30bd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
30be0 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
30bf0 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
30c00 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
30c10 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69  **.** ^Registeri
30c20 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69  ng a NULL functi
30c30 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  on disables the 
30c40 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
30c50 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74  ^When the commit
30c60 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72   hook callback r
30c70 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a  outine returns z
30c80 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54  ero, the [COMMIT
30c90 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69  ].** operation i
30ca0 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e  s allowed to con
30cb0 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20  tinue normally. 
30cc0 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20   ^If the commit 
30cd0 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20  hook.** returns 
30ce0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
30cf0 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63  he [COMMIT] is c
30d00 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20  onverted into a 
30d10 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e  [ROLLBACK]..** ^
30d20 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  The rollback hoo
30d30 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
30d40 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20  a rollback that 
30d50 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63  results from a c
30d60 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65  ommit.** hook re
30d70 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f  turning non-zero
30d80 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75  , just as it wou
30d90 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f  ld be with any o
30da0 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a  ther rollback..*
30db0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
30dc0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41  rposes of this A
30dd0 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f  PI, a transactio
30de0 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68 61 76  n is said to hav
30df0 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64  e been.** rolled
30e00 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c   back if an expl
30e10 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20  icit "ROLLBACK" 
30e20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65  statement is exe
30e30 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20  cuted, or.** an 
30e40 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61  error or constra
30e50 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d  int causes an im
30e60 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20  plicit rollback 
30e70 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68  to occur..** ^Th
30e80 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62  e rollback callb
30e90 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  ack is not invok
30ea0 65 64 20 69 66 20 61 20 74 72 61 6e 73 61 63 74  ed if a transact
30eb0 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61  ion is.** automa
30ec0 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
30ed0 61 63 6b 20 62 65 63 61 75 73 65 20 74 68 65 20  ack because the 
30ee0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30ef0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
30f00 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
30f10 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74  e [sqlite3_updat
30f20 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66  e_hook()] interf
30f30 61 63 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ace..*/.void *sq
30f40 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
30f50 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  k(sqlite3*, int(
30f60 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
30f70 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
30f80 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
30f90 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
30fa0 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
30fb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30fc0 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
30fd0 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
30fe0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
30ff0 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
31000 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
31010 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
31020 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
31030 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
31040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31050 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
31060 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
31070 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
31080 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
31090 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
310a0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
310b0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
310c0 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
310d0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
310e0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
310f0 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
31100 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
31110 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
31120 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
31130 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
31140 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
31150 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
31160 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
31170 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
31180 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
31190 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
311a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
311b0 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
311c0 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
311d0 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
311e0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
311f0 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
31200 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
31210 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
31220 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
31230 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
31240 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
31250 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
31260 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
31270 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
31280 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
31290 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
312a0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
312b0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
312c0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
312d0 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
312e0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
312f0 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
31300 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
31310 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
31320 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
31330 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
31340 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
31350 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
31360 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
31370 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
31380 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
31390 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
313a0 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
313b0 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
313c0 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
313d0 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
313e0 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
313f0 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
31400 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
31410 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
31420 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
31430 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
31440 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
31450 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
31460 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
31470 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
31480 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
31490 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
314a0 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
314b0 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
314c0 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
314d0 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
314e0 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
314f0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
31500 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
31510 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
31520 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
31530 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
31540 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
31550 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
31560 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
31570 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
31580 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
31590 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
315a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
315b0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
315c0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
315d0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
315e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
315f0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
31600 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
31610 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
31620 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
31630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31640 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
31650 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
31660 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
31670 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
31680 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
31690 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
316a0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
316b0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
316c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
316d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
316e0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
316f0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
31700 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
31710 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
31720 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
31730 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
31740 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31750 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
31760 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
31770 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
31780 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
31790 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
317a0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
317b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
317c0 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
317d0 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
317e0 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
317f0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
31800 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
31810 6f 6b 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ok()], [sqlite3_
31820 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d  rollback_hook()]
31830 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
31840 33 5f 70 72 65 75 70 64 61 74 65 5f 68 6f 6f 6b  3_preupdate_hook
31850 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e 0a  ()] interfaces..
31860 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
31870 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20  _update_hook(.  
31880 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
31890 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20  d(*)(void *,int 
318a0 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68  ,char const *,ch
318b0 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74  ar const *,sqlit
318c0 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69  e3_int64),.  voi
318d0 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  d*.);../*.** CAP
318e0 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72  I3REF: Enable Or
318f0 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64 20   Disable Shared 
31900 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b  Pager Cache.** K
31910 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64  EYWORDS: {shared
31920 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28   cache}.**.** ^(
31930 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61  This routine ena
31940 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
31950 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20   the sharing of 
31960 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61 63  the database cac
31970 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61  he.** and schema
31980 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
31990 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61   between [databa
319a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20  se connection | 
319b0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20  connections].** 
319c0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
319d0 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73  base. Sharing is
319e0 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
319f0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65  argument is true
31a00 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64  .** and disabled
31a10 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   if the argument
31a20 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a   is false.)^.**.
31a30 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e  ** ^Cache sharin
31a40 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64  g is enabled and
31a50 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e   disabled for an
31a60 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e   entire process.
31a70 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63 68  .** This is a ch
31a80 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74  ange as of SQLit
31a90 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e  e version 3.5.0.
31aa0 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f   In prior versio
31ab0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a  ns of SQLite,.**
31ac0 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61   sharing was ena
31ad0 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
31ae0 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61 64   for each thread
31af0 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
31b00 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20 73  ** ^(The cache s
31b10 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20  haring mode set 
31b20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  by this interfac
31b30 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75  e effects all su
31b40 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c  bsequent.** call
31b50 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  s to [sqlite3_op
31b60 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
31b70 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20  open_v2()], and 
31b80 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
31b90 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  )]..** Existing 
31ba0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31bb0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73  ions continue us
31bc0 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f  e the sharing mo
31bd0 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69  de.** that was i
31be0 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65 20  n effect at the 
31bf0 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f  time they were o
31c00 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  pened.)^.**.** ^
31c10 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  (This routine re
31c20 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
31c30 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63 68  ] if shared cach
31c40 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72  e was enabled or
31c50 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63   disabled.** suc
31c60 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b  cessfully.  An [
31c70 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
31c80 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73  eturned otherwis
31c90 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72  e.)^.**.** ^Shar
31ca0 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73 61  ed cache is disa
31cb0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
31cc0 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74 20   But this might 
31cd0 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74  change in.** fut
31ce0 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
31cf0 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61  SQLite.  Applica
31d00 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20  tions that care 
31d10 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20  about shared.** 
31d20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73 68  cache setting sh
31d30 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c  ould set it expl
31d40 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65  icitly..**.** Se
31d50 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65  e Also:  [SQLite
31d60 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f   Shared-Cache Mo
31d70 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  de].*/.int sqlit
31d80 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
31d90 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a  _cache(int);../*
31da0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74  .** CAPI3REF: At
31db0 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65  tempt To Free He
31dc0 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20  ap Memory.**.** 
31dd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
31de0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e  ease_memory() in
31df0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
31e00 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73   to free N bytes
31e10 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  .** of heap memo
31e20 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69  ry by deallocati
31e30 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  ng non-essential
31e40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
31e50 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74  ons.** held by t
31e60 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62 72  he database libr
31e70 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73  ary.   Memory us
31e80 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74 61  ed to cache data
31e90 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f  base.** pages to
31ea0 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
31eb0 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70  ance is an examp
31ec0 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74  le of non-essent
31ed0 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ial memory..** ^
31ee0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
31ef0 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73  memory() returns
31f00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
31f10 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72  ytes actually fr
31f20 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69  eed,.** which mi
31f30 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c  ght be more or l
31f40 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f  ess than the amo
31f50 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a  unt requested..*
31f60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
31f70 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20  elease_memory() 
31f80 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d  routine is a no-
31f90 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72  op returning zer
31fa0 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  o.** if SQLite i
31fb0 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77  s not compiled w
31fc0 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  ith [SQLITE_ENAB
31fd0 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45  LE_MEMORY_MANAGE
31fe0 4d 45 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  MENT]..*/.int sq
31ff0 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
32000 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mory(int);../*.*
32010 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f  * CAPI3REF: Impo
32020 73 65 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65  se A Limit On He
32030 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54  ap Size.**.** ^T
32040 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  he sqlite3_soft_
32050 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69  heap_limit64() i
32060 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 61 6e  nterface sets an
32070 64 2f 6f 72 20 71 75 65 72 69 65 73 20 74 68 65  d/or queries the
32080 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f  .** soft limit o
32090 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  n the amount of 
320a0 68 65 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74  heap memory that
320b0 20 6d 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65   may be allocate
320c0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  d by SQLite..** 
320d0 5e 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20  ^SQLite strives 
320e0 74 6f 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d  to keep heap mem
320f0 6f 72 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20  ory utilization 
32100 62 65 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68  below the soft h
32110 65 61 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20  eap.** limit by 
32120 72 65 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d  reducing the num
32130 62 65 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c  ber of pages hel
32140 64 20 69 6e 20 74 68 65 20 70 61 67 65 20 63 61  d in the page ca
32150 63 68 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d  che.** as heap m
32160 65 6d 6f 72 79 20 75 73 61 67 65 73 20 61 70 70  emory usages app
32170 72 6f 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69  roaches the limi
32180 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20  t..** ^The soft 
32190 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73  heap limit is "s
321a0 6f 66 74 22 20 62 65 63 61 75 73 65 20 65 76 65  oft" because eve
321b0 6e 20 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20  n though SQLite 
321c0 73 74 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a  strives to stay.
321d0 2a 2a 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d  ** below the lim
321e0 69 74 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65  it, it will exce
321f0 65 64 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74  ed the limit rat
32200 68 65 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74  her than generat
32210 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f  e.** an [SQLITE_
32220 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49  NOMEM] error.  I
32230 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
32240 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
32250 69 74 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f  it .** is adviso
32260 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ry only..**.** ^
32270 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
32280 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f   from sqlite3_so
32290 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
322a0 29 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  ) is the size of
322b0 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61  .** the soft hea
322c0 70 20 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f  p limit prior to
322d0 20 74 68 65 20 63 61 6c 6c 2e 20 20 5e 49 66 20   the call.  ^If 
322e0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69  the argument N i
322f0 73 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68  s negative.** th
32300 65 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20  en no change is 
32310 6d 61 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74  made to the soft
32320 20 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65   heap limit.  He
32330 6e 63 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74  nce, the current
32340 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20  .** size of the 
32350 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
32360 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
32370 64 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  d by invoking.**
32380 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
32390 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74  ap_limit64() wit
323a0 68 20 61 20 6e 65 67 61 74 69 76 65 20 61 72 67  h a negative arg
323b0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ument..**.** ^If
323c0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20   the argument N 
323d0 69 73 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65  is zero then the
323e0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
323f0 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a   is disabled..**
32400 0a 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68  .** ^(The soft h
32410 65 61 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  eap limit is not
32420 20 65 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65   enforced in the
32430 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
32440 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e  ntation.** if on
32450 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c  e or more of fol
32460 6c 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e  lowing condition
32470 73 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a  s are true:.**.*
32480 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
32490 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
324a0 69 74 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72  it is set to zer
324b0 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72  o..** <li> Memor
324c0 79 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20  y accounting is 
324d0 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
324e0 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20   combination of 
324f0 74 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c  the.**      [sql
32500 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
32510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
32520 54 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72  TATUS],...) star
32530 74 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e  t-time option an
32540 64 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53  d.**      the [S
32550 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
32560 4d 53 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65  MSTATUS] compile
32570 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
32580 20 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61   <li> An alterna
32590 74 69 76 65 20 70 61 67 65 20 63 61 63 68 65 20  tive page cache 
325a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
325b0 73 20 73 70 65 63 69 66 65 64 20 75 73 69 6e 67  s specifed using
325c0 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65  .**      [sqlite
325d0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
325e0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
325f0 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  ,...)..** <li> T
32600 68 65 20 70 61 67 65 20 63 61 63 68 65 20 61 6c  he page cache al
32610 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20 69 74 73  locates from its
32620 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c   own memory pool
32630 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20   supplied.**    
32640 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f    by [sqlite3_co
32650 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f  nfig]([SQLITE_CO
32660 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c  NFIG_PAGECACHE],
32670 2e 2e 2e 29 20 72 61 74 68 65 72 20 74 68 61 6e  ...) rather than
32680 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20 74 68  .**      from th
32690 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e  e heap..** </ul>
326a0 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69  )^.**.** Beginni
326b0 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76  ng with SQLite v
326c0 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68  ersion 3.7.3, th
326d0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
326e0 74 20 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a  t is enforced.**
326f0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
32700 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
32710 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
32720 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
32730 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  NT].** compile-t
32740 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e  ime option is in
32750 76 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b 53 51  voked.  With [SQ
32760 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
32770 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a  RY_MANAGEMENT],.
32780 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ** the soft heap
32790 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63   limit is enforc
327a0 65 64 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f  ed on every memo
327b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20  ry allocation.  
327c0 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49  Without.** [SQLI
327d0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
327e0 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68  _MANAGEMENT], th
327f0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
32800 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63  t is only enforc
32810 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72  ed.** when memor
32820 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62  y is allocated b
32830 79 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  y the page cache
32840 2e 20 20 54 65 73 74 69 6e 67 20 73 75 67 67 65  .  Testing sugge
32850 73 74 73 20 74 68 61 74 20 62 65 63 61 75 73 65  sts that because
32860 0a 2a 2a 20 74 68 65 20 70 61 67 65 20 63 61 63  .** the page cac
32870 68 65 20 69 73 20 74 68 65 20 70 72 65 64 6f 6d  he is the predom
32880 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75 73 65  inate memory use
32890 72 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73  r in SQLite, mos
328a0 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
328b0 73 20 77 69 6c 6c 20 61 63 68 69 65 76 65 20 61  s will achieve a
328c0 64 65 71 75 61 74 65 20 73 6f 66 74 20 68 65 61  dequate soft hea
328d0 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d  p limit enforcem
328e0 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74  ent without.** t
328f0 68 65 20 75 73 65 20 6f 66 20 5b 53 51 4c 49 54  he use of [SQLIT
32900 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
32910 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a  MANAGEMENT]..**.
32920 2a 2a 20 54 68 65 20 63 69 72 63 75 6d 73 74 61  ** The circumsta
32930 6e 63 65 73 20 75 6e 64 65 72 20 77 68 69 63 68  nces under which
32940 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66   SQLite will enf
32950 6f 72 63 65 20 74 68 65 20 73 6f 66 74 20 68 65  orce the soft he
32960 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20  ap limit may.** 
32970 63 68 61 6e 67 65 73 20 69 6e 20 66 75 74 75 72  changes in futur
32980 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
32990 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  Lite..*/.sqlite3
329a0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73  _int64 sqlite3_s
329b0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
329c0 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e  (sqlite3_int64 N
329d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
329e0 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 53  EF: Deprecated S
329f0 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49  oft Heap Limit I
32a00 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52  nterface.** DEPR
32a10 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69  ECATED.**.** Thi
32a20 73 20 69 73 20 61 20 64 65 70 72 65 63 61 74 65  s is a deprecate
32a30 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
32a40 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
32a50 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
32a60 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  * interface.  Th
32a70 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72  is routine is pr
32a80 6f 76 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f  ovided for histo
32a90 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
32aa0 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c  ity.** only.  Al
32ab0 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  l new applicatio
32ac0 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  ns should use th
32ad0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f  e.** [sqlite3_so
32ae0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
32af0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61 74  )] interface rat
32b00 68 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e  her than this on
32b10 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50  e..*/.SQLITE_DEP
32b20 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
32b30 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
32b40 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f  imit(int N);.../
32b50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
32b60 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20  xtract Metadata 
32b70 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f  About A Column O
32b80 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20  f A Table.**.** 
32b90 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
32ba0 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61  turns metadata a
32bb0 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20  bout a specific 
32bc0 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63  column of a spec
32bd0 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65  ific.** database
32be0 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c   table accessibl
32bf0 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74  e using the [dat
32c00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32c10 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73  ] handle.** pass
32c20 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
32c30 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
32c40 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f  t..**.** ^The co
32c50 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69  lumn is identifi
32c60 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
32c70 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  , third and four
32c80 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
32c90 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f  .** this functio
32ca0 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  n. ^The second p
32cb0 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68  arameter is eith
32cc0 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  er the name of t
32cd0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28  he database.** (
32ce0 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65  i.e. "main", "te
32cf0 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63  mp", or an attac
32d00 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f  hed database) co
32d10 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65  ntaining the spe
32d20 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20  cified.** table 
32d30 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20  or NULL. ^If it 
32d40 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c  is NULL, then al
32d50 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  l attached datab
32d60 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65  ases are searche
32d70 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62  d.** for the tab
32d80 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  le using the sam
32d90 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64  e algorithm used
32da0 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65   by the database
32db0 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65   engine to.** re
32dc0 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65  solve unqualifie
32dd0 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63  d table referenc
32de0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  es..**.** ^The t
32df0 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
32e00 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
32e10 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  is function are 
32e20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  the table and co
32e30 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20  lumn.** name of 
32e40 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75  the desired colu
32e50 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  mn, respectively
32e60 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65  . Neither of the
32e70 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  se parameters.**
32e80 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   may be NULL..**
32e90 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73  .** ^Metadata is
32ea0 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69   returned by wri
32eb0 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f  ting to the memo
32ec0 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73  ry locations pas
32ed0 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a  sed as the 5th.*
32ee0 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  * and subsequent
32ef0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
32f00 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41  his function. ^A
32f10 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75  ny of these argu
32f20 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20  ments may be.** 
32f30 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63  NULL, in which c
32f40 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ase the correspo
32f50 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66  nding element of
32f60 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69   metadata is omi
32f70 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62  tted..**.** ^(<b
32f80 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
32f90 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
32fa0 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72  .** <tr><th> Par
32fb0 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70  ameter <th> Outp
32fc0 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ut<br>Type <th> 
32fd0 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a   Description.**.
32fe0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20  ** <tr><td> 5th 
32ff0 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
33000 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a   <td> Data type.
33010 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20  ** <tr><td> 6th 
33020 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a  <td> const char*
33030 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65   <td> Name of de
33040 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20  fault collation 
33050 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e  sequence.** <tr>
33060 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e  <td> 7th <td> in
33070 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54  t         <td> T
33080 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61  rue if column ha
33090 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e  s a NOT NULL con
330a0 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c  straint.** <tr><
330b0 74 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74  td> 8th <td> int
330c0 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
330d0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
330e0 70 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d  part of the PRIM
330f0 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c  ARY KEY.** <tr><
33100 74 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74  td> 9th <td> int
33110 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
33120 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20  ue if column is 
33130 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a  [AUTOINCREMENT].
33140 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c  ** </table>.** <
33150 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
33160 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
33170 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
33180 68 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69  he character poi
33190 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66  nters returned f
331a0 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72  or the.** declar
331b0 61 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63  ation type and c
331c0 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63  ollation sequenc
331d0 65 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20  e is valid only 
331e0 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a  until the next.*
331f0 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51  * call to any SQ
33200 4c 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f  Lite API functio
33210 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
33220 20 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65   specified table
33230 20 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76   is actually a v
33240 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63  iew, an [error c
33250 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
33260 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
33270 73 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e  specified column
33280 20 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69   is "rowid", "oi
33290 64 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20  d" or "_rowid_" 
332a0 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47  and an.** [INTEG
332b0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
332c0 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20  column has been 
332d0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
332e0 72 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  red, then the ou
332f0 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  tput.** paramete
33300 72 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74  rs are set for t
33310 68 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  he explicitly de
33320 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e  clared column. ^
33330 28 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a  (If there is no.
33340 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  ** explicitly de
33350 63 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20  clared [INTEGER 
33360 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c  PRIMARY KEY] col
33370 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75  umn, then the ou
33380 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  tput.** paramete
33390 72 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f  rs are set as fo
333a0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72  llows:.**.** <pr
333b0 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74  e>.**     data t
333c0 79 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a  ype: "INTEGER".*
333d0 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20  *     collation 
333e0 73 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52  sequence: "BINAR
333f0 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75  Y".**     not nu
33400 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69  ll: 0.**     pri
33410 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20  mary key: 1.**  
33420 20 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e     auto incremen
33430 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e  t: 0.** </pre>)^
33440 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75  .**.** ^(This fu
33450 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20  nction may load 
33460 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65  one or more sche
33470 6d 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73  mas from databas
33480 65 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a  e files. If an.*
33490 2a 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  * error occurs d
334a0 75 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65  uring this proce
334b0 73 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65  ss, or if the re
334c0 71 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72  quested table or
334d0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f   column.** canno
334e0 74 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b  t be found, an [
334f0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
33500 65 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65  eturned and an e
33510 72 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66  rror message lef
33520 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74  t.** in the [dat
33530 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33540 5d 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76  ] (to be retriev
33550 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33  ed using sqlite3
33560 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a  _errmsg()).)^.**
33570 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73  .** ^This API is
33580 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
33590 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
335a0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
335b0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
335c0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
335d0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
335e0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65  cessor symbol de
335f0 66 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  fined..*/.int sq
33600 6c 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75  lite3_table_colu
33610 6d 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73  mn_metadata(.  s
33620 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
33630 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f             /* Co
33640 6e 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20  nnection handle 
33650 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
33660 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
33670 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d   /* Database nam
33680 65 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63  e or NULL */.  c
33690 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c  onst char *zTabl
336a0 65 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61  eName,     /* Ta
336b0 62 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f  ble name */.  co
336c0 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d  nst char *zColum
336d0 6e 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c  nName,    /* Col
336e0 75 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68  umn name */.  ch
336f0 61 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74  ar const **pzDat
33700 61 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54  aType,    /* OUT
33710 50 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61  PUT: Declared da
33720 74 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61  ta type */.  cha
33730 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c  r const **pzColl
33740 53 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50  Seq,     /* OUTP
33750 55 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65  UT: Collation se
33760 71 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20  quence name */. 
33770 20 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20   int *pNotNull, 
33780 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
33790 4f 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20  OUTPUT: True if 
337a0 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61  NOT NULL constra
337b0 69 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20  int exists */.  
337c0 69 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79  int *pPrimaryKey
337d0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  ,           /* O
337e0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63  UTPUT: True if c
337f0 6f 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b  olumn part of PK
33800 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f   */.  int *pAuto
33810 69 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20  inc             
33820 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
33830 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61  e if column is a
33840 75 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f  uto-increment */
33850 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
33860 52 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74  REF: Load An Ext
33870 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ension.**.** ^Th
33880 69 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61  is interface loa
33890 64 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74  ds an SQLite ext
338a0 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66  ension library f
338b0 72 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69  rom the named fi
338c0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  le..**.** ^The s
338d0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
338e0 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
338f0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f  e attempts to lo
33900 61 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  ad an.** SQLite 
33910 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72  extension librar
33920 79 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74  y contained in t
33930 68 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a  he file zFile..*
33940 2a 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20  *.** ^The entry 
33950 70 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a  point is zProc..
33960 2a 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65  ** ^zProc may be
33970 20 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73   0, in which cas
33980 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  e the name of th
33990 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a  e entry point.**
339a0 20 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71   defaults to "sq
339b0 6c 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f  lite3_extension_
339c0 69 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73  init"..** ^The s
339d0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
339e0 6e 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63  nsion() interfac
339f0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  e returns.** [SQ
33a00 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
33a10 65 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ess and [SQLITE_
33a20 45 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68  ERROR] if someth
33a30 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
33a40 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
33a50 6f 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72  occurs and pzErr
33a60 4d 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68  Msg is not 0, th
33a70 65 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  en the.** [sqlit
33a80 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
33a90 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73  n()] interface s
33aa0 68 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a  hall attempt to.
33ab0 2a 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73  ** fill *pzErrMs
33ac0 67 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73  g with error mes
33ad0 73 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64  sage text stored
33ae0 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62   in memory.** ob
33af0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
33b00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
33b10 54 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  The calling func
33b20 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66  tion.** should f
33b30 72 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20  ree this memory 
33b40 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
33b50 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
33b60 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f  ** ^Extension lo
33b70 61 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e  ading must be en
33b80 61 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  abled using.** [
33b90 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
33ba0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
33bb0 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
33bc0 67 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f  g this API,.** o
33bd0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
33be0 72 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e  r will be return
33bf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ed..**.** See al
33c00 73 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74  so the [load_ext
33c10 65 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e  ension() SQL fun
33c20 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  ction]..*/.int s
33c30 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
33c40 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  nsion(.  sqlite3
33c50 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
33c60 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e  * Load the exten
33c70 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64  sion into this d
33c80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33c90 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
33ca0 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a  ar *zFile,    /*
33cb0 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61   Name of the sha
33cc0 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  red library cont
33cd0 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e  aining extension
33ce0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
33cf0 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45   *zProc,    /* E
33d00 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72  ntry point.  Der
33d10 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20  ived from zFile 
33d20 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a  if 0 */.  char *
33d30 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20  *pzErrMsg       
33d40 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73  /* Put error mes
33d50 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74  sage here if not
33d60 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   0 */.);../*.** 
33d70 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
33d80 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
33d90 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
33da0 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74  .** ^So as not t
33db0 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20  o open security 
33dc0 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61  holes in older a
33dd0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
33de0 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72   are.** unprepar
33df0 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  ed to deal with 
33e00 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
33e10 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e  g, and as a mean
33e20 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a  s of disabling.*
33e30 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * extension load
33e40 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61  ing while evalua
33e50 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65  ting user-entere
33e60 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f  d SQL, the follo
33e70 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70  wing API.** is p
33e80 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20  rovided to turn 
33e90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
33ea0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d  d_extension()] m
33eb0 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20  echanism on and 
33ec0 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65  off..**.** ^Exte
33ed0 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73  nsion loading is
33ee0 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
33ef0 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36   See ticket #186
33f00 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20  3..** ^Call the 
33f10 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
33f20 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
33f30 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f  routine with ono
33f40 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e  ff==1.** to turn
33f50 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
33f60 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69  ng on and call i
33f70 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20  t with onoff==0 
33f80 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61  to turn.** it ba
33f90 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f  ck off again..*/
33fa0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61  .int sqlite3_ena
33fb0 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
33fc0 6f 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  on(sqlite3 *db, 
33fd0 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a  int onoff);../*.
33fe0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
33ff0 6f 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20  omatically Load 
34000 53 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b 65  Statically Linke
34010 64 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a  d Extensions.**.
34020 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
34030 63 65 20 63 61 75 73 65 73 20 74 68 65 20 78 45  ce causes the xE
34040 6e 74 72 79 50 6f 69 6e 74 28 29 20 66 75 6e 63  ntryPoint() func
34050 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
34060 65 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 6e  ed for.** each n
34070 65 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ew [database con
34080 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 69 73  nection] that is
34090 20 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69   created.  The i
340a0 64 65 61 20 68 65 72 65 20 69 73 20 74 68 61 74  dea here is that
340b0 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  .** xEntryPoint(
340c0 29 20 69 73 20 74 68 65 20 65 6e 74 72 79 20 70  ) is the entry p
340d0 6f 69 6e 74 20 66 6f 72 20 61 20 73 74 61 74 69  oint for a stati
340e0 63 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51 4c  cally linked SQL
340f0 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a 2a  ite extension.**
34100 20 74 68 61 74 20 69 73 20 74 6f 20 62 65 20 61   that is to be a
34110 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f 61  utomatically loa
34120 64 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65 77  ded into all new
34130 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
34140 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45  tions..**.** ^(E
34150 76 65 6e 20 74 68 6f 75 67 68 20 74 68 65 20 66  ven though the f
34160 75 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79 70  unction prototyp
34170 65 20 73 68 6f 77 73 20 74 68 61 74 20 78 45 6e  e shows that xEn
34180 74 72 79 50 6f 69 6e 74 28 29 20 74 61 6b 65 73  tryPoint() takes
34190 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  .** no arguments
341a0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 76 6f 69   and returns voi
341b0 64 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  d, SQLite invoke
341c0 73 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  s xEntryPoint() 
341d0 77 69 74 68 20 74 68 72 65 65 0a 2a 2a 20 61 72  with three.** ar
341e0 67 75 6d 65 6e 74 73 20 61 6e 64 20 65 78 70 65  guments and expe
341f0 63 74 73 20 61 6e 64 20 69 6e 74 65 67 65 72 20  cts and integer 
34200 72 65 73 75 6c 74 20 61 73 20 69 66 20 74 68 65  result as if the
34210 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68   signature of th
34220 65 0a 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e 74  e.** entry point
34230 20 77 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f 77   where as follow
34240 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
34250 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26 6e  uote><pre>.** &n
34260 62 73 70 3b 20 20 69 6e 74 20 78 45 6e 74 72 79  bsp;  int xEntry
34270 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70 3b  Point(.** &nbsp;
34280 20 20 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c      sqlite3 *db,
34290 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f  .** &nbsp;    co
342a0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  nst char **pzErr
342b0 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  Msg,.** &nbsp;  
342c0 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
342d0 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
342e0 6e 65 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20 26  nes *pThunk.** &
342f0 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f 70  nbsp;  );.** </p
34300 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
34310 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  )^.**.** If the 
34320 78 45 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75 74  xEntryPoint rout
34330 69 6e 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  ine encounters a
34340 6e 20 65 72 72 6f 72 2c 20 69 74 20 73 68 6f 75  n error, it shou
34350 6c 64 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d 73  ld make *pzErrMs
34360 67 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e  g.** point to an
34370 20 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72   appropriate err
34380 6f 72 20 6d 65 73 73 61 67 65 20 28 6f 62 74 61  or message (obta
34390 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
343a0 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a 2a  e3_mprintf()]).*
343b0 2a 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20  * and return an 
343c0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
343d0 6f 72 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c 69  or code].  ^SQLi
343e0 74 65 20 65 6e 73 75 72 65 73 20 74 68 61 74 20  te ensures that 
343f0 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73 20  *pzErrMsg.** is 
34400 4e 55 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c 6c  NULL before call
34410 69 6e 67 20 74 68 65 20 78 45 6e 74 72 79 50 6f  ing the xEntryPo
34420 69 6e 74 28 29 2e 20 20 5e 53 51 4c 69 74 65 20  int().  ^SQLite 
34430 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b  will invoke.** [
34440 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
34450 6f 6e 20 2a 70 7a 45 72 72 4d 73 67 20 61 66 74  on *pzErrMsg aft
34460 65 72 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  er xEntryPoint()
34470 20 72 65 74 75 72 6e 73 2e 20 20 5e 49 66 20 61   returns.  ^If a
34480 6e 79 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e  ny.** xEntryPoin
34490 74 28 29 20 72 65 74 75 72 6e 73 20 61 6e 20 65  t() returns an e
344a0 72 72 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69 74  rror, the [sqlit
344b0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
344c0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a  ite3_open16()],.
344d0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
344e0 70 65 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20 74  pen_v2()] call t
344f0 68 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65  hat provoked the
34500 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77   xEntryPoint() w
34510 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  ill fail..**.** 
34520 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
34530 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
34540 58 29 20 77 69 74 68 20 61 6e 20 65 6e 74 72 79  X) with an entry
34550 20 70 6f 69 6e 74 20 58 20 74 68 61 74 20 69 73   point X that is
34560 20 61 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20 74   already.** on t
34570 68 65 20 6c 69 73 74 20 6f 66 20 61 75 74 6f 6d  he list of autom
34580 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20  atic extensions 
34590 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
345a0 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20 70  -op. ^No entry p
345b0 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  oint.** will be 
345c0 63 61 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61 6e  called more than
345d0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 64   once for each d
345e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
345f0 6f 6e 20 74 68 61 74 20 69 73 20 6f 70 65 6e 65  on that is opene
34600 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
34610 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  o: [sqlite3_rese
34620 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  t_auto_extension
34630 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
34640 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69  te3_auto_extensi
34650 6f 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79  on(void (*xEntry
34660 50 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a  Point)(void));..
34670 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34680 52 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20  Reset Automatic 
34690 45 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e  Extension Loadin
346a0 67 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  g.**.** ^This in
346b0 74 65 72 66 61 63 65 20 64 69 73 61 62 6c 65 73  terface disables
346c0 20 61 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20 65   all automatic e
346d0 78 74 65 6e 73 69 6f 6e 73 20 70 72 65 76 69 6f  xtensions previo
346e0 75 73 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  usly.** register
346f0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
34700 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
34710 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  ()]..*/.void sql
34720 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f  ite3_reset_auto_
34730 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b  extension(void);
34740 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ../*.** The inte
34750 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72  rface to the vir
34760 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
34770 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c  nism is currentl
34780 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
34790 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
347a0 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
347b0 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
347c0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
347d0 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
347e0 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
347f0 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
34800 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
34810 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
34820 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
34830 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
34840 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
34850 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
34860 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
34870 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
34880 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
34890 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
348a0 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
348b0 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20  *.** Structures 
348c0 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74  used by the virt
348d0 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66  ual table interf
348e0 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ace.*/.typedef s
348f0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
34900 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b  ab sqlite3_vtab;
34910 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
34920 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
34930 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  fo sqlite3_index
34940 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73  _info;.typedef s
34950 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74  truct sqlite3_vt
34960 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65  ab_cursor sqlite
34970 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74  3_vtab_cursor;.t
34980 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
34990 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c  lite3_module sql
349a0 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a  ite3_module;../*
349b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
349c0 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65  rtual Table Obje
349d0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
349e0 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
349f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f  virtual table mo
34a00 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73  dule}.**.** This
34a10 20 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65   structure, some
34a20 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 61  times called a a
34a30 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   "virtual table 
34a40 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66  module", .** def
34a50 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d 65  ines the impleme
34a60 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69  ntation of a [vi
34a70 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20  rtual tables].  
34a80 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74 75  .** This structu
34a90 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74  re consists most
34aa0 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f  ly of methods fo
34ab0 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a  r the module..**
34ac0 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c 20 74  .** ^A virtual t
34ad0 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20 63  able module is c
34ae0 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69 6e  reated by fillin
34af0 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 65 6e  g in a persisten
34b00 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  t.** instance of
34b10 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65 20   this structure 
34b20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70 6f  and passing a po
34b30 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  inter to that in
34b40 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71  stance.** to [sq
34b50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
34b60 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ule()] or [sqlit
34b70 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
34b80 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  _v2()]..** ^The 
34b90 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65 6d  registration rem
34ba0 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  ains valid until
34bb0 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64 20   it is replaced 
34bc0 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a 2a  by a different.*
34bd0 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69  * module or unti
34be0 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  l the [database 
34bf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73  connection] clos
34c00 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  es.  The content
34c10 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72 75  .** of this stru
34c20 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20 63  cture must not c
34c30 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20 69  hange while it i
34c40 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74  s registered wit
34c50 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61 73  h.** any databas
34c60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f  e connection..*/
34c70 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
34c80 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69  module {.  int i
34c90 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28  Version;.  int (
34ca0 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74 65  *xCreate)(sqlite
34cb0 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
34cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
34cd0 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
34ce0 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
34cf0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
34d00 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
34d10 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
34d20 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74    int (*xConnect
34d30 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
34d40 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
34d50 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
34d60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
34d70 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
34d80 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
34d90 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
34da0 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
34db0 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c 69  xBestIndex)(sqli
34dc0 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c  te3_vtab *pVTab,
34dd0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
34de0 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  nfo*);.  int (*x
34df0 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69  Disconnect)(sqli
34e00 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
34e10 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74 72  ;.  int (*xDestr
34e20 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  oy)(sqlite3_vtab
34e30 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
34e40 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
34e50 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
34e60 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
34e70 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20  r **ppCursor);. 
34e80 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
34e90 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
34ea0 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  or*);.  int (*xF
34eb0 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f 76  ilter)(sqlite3_v
34ec0 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74  tab_cursor*, int
34ed0 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63   idxNum, const c
34ee0 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20 20  har *idxStr,.   
34ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
34f00 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f 76   argc, sqlite3_v
34f10 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20  alue **argv);.  
34f20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71 6c  int (*xNext)(sql
34f30 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72  ite3_vtab_cursor
34f40 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66  *);.  int (*xEof
34f50 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
34f60 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28  ursor*);.  int (
34f70 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65  *xColumn)(sqlite
34f80 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20  3_vtab_cursor*, 
34f90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34fa0 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
34fb0 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33 5f  xRowid)(sqlite3_
34fc0 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71  vtab_cursor*, sq
34fd0 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f  lite3_int64 *pRo
34fe0 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  wid);.  int (*xU
34ff0 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f 76  pdate)(sqlite3_v
35000 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  tab *, int, sqli
35010 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71  te3_value **, sq
35020 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a  lite3_int64 *);.
35030 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29 28    int (*xBegin)(
35040 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
35050 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  Tab);.  int (*xS
35060 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ync)(sqlite3_vta
35070 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
35080 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69   (*xCommit)(sqli
35090 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
350a0 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62  ;.  int (*xRollb
350b0 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ack)(sqlite3_vta
350c0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
350d0 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e   (*xFindFunction
350e0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
350f0 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c  pVtab, int nArg,
35100 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
35110 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  me,.            
35120 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20             void 
35130 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69 74  (**pxFunc)(sqlit
35140 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
35150 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
35160 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
35170 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a 2a           void **
35180 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  ppArg);.  int (*
35190 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  xRename)(sqlite3
351a0 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63 6f  _vtab *pVtab, co
351b0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b  nst char *zNew);
351c0 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
351d0 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
351e0 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66 6f  le Indexing Info
351f0 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57 4f  rmation.** KEYWO
35200 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e 64  RDS: sqlite3_ind
35210 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54 68  ex_info.**.** Th
35220 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  e sqlite3_index_
35230 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20 61  info structure a
35240 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63 74  nd its substruct
35250 75 72 65 73 20 69 73 20 75 73 65 64 20 61 73 20  ures is used as 
35260 70 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  part.** of the [
35270 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 69  virtual table] i
35280 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 70  nterface to.** p
35290 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ass information 
352a0 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76 65  into and receive
352b0 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d 20   the reply from 
352c0 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d  the [xBestIndex]
352d0 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20  .** method of a 
352e0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
352f0 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69 65  odule].  The fie
35300 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70 75  lds under **Inpu
35310 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a 20  ts** are the.** 
35320 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74 49  inputs to xBestI
35330 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65 61  ndex and are rea
35340 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49 6e  d-only.  xBestIn
35350 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73 0a  dex inserts its.
35360 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
35370 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a 20  the **Outputs** 
35380 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  fields..**.** ^(
35390 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b  The aConstraint[
353a0 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73 20  ] array records 
353b0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
353c0 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65 20  straints of the 
353d0 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  form:.**.** <blo
353e0 63 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d 6e 20 4f  ckquote>column O
353f0 50 20 65 78 70 72 3c 2f 62 6c 6f 63 6b 71 75 6f  P expr</blockquo
35400 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65 20  te>.**.** where 
35410 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20 26  OP is =, &lt;, &
35420 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20 26  lt;=, &gt;, or &
35430 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20 70  gt;=.)^  ^(The p
35440 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61 74  articular operat
35450 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64 20  or is.** stored 
35460 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  in aConstraint[]
35470 2e 6f 70 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  .op using one of
35480 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
35490 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
354a0 5f 45 51 20 7c 20 53 51 4c 49 54 45 5f 49 4e 44  _EQ | SQLITE_IND
354b0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 20 76  EX_CONSTRAINT_ v
354c0 61 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20 5e 28 54  alues].)^.** ^(T
354d0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
354e0 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65 64  column is stored
354f0 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61 69   in.** aConstrai
35500 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e 20  nt[].iColumn.)^ 
35510 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d   ^(aConstraint[]
35520 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45 20  .usable is TRUE 
35530 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20 6f  if the.** expr o
35540 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  n the right-hand
35550 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76 61   side can be eva
35560 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75 73  luated (and thus
35570 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 0a   the constraint.
35580 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61 6e  ** is usable) an
35590 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63 61  d false if it ca
355a0 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  nnot.)^.**.** ^T
355b0 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75 74  he optimizer aut
355c0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65 72  omatically inver
355d0 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65 20  ts terms of the 
355e0 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63 6f  form "expr OP co
355f0 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61 6b  lumn".** and mak
35600 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69 66  es other simplif
35610 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65 20  ications to the 
35620 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e 20  WHERE clause in 
35630 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  an attempt to.**
35640 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48 45   get as many WHE
35650 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73 20  RE clause terms 
35660 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73 68  into the form sh
35670 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f 73  own above as pos
35680 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20 61  sible..** ^The a
35690 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72 72  Constraint[] arr
356a0 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ay only reports 
356b0 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72  WHERE clause ter
356c0 6d 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20 72  ms that are.** r
356d0 65 6c 65 76 61 6e 74 20 74 6f 20 74 68 65 20 70  elevant to the p
356e0 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75 61  articular virtua
356f0 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71 75  l table being qu
35700 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  eried..**.** ^In
35710 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
35720 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c 61  the ORDER BY cla
35730 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69 6e  use is stored in
35740 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a 20   aOrderBy[]..** 
35750 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61 4f  ^Each term of aO
35760 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20 61  rderBy records a
35770 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 4f   column of the O
35780 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e 0a  RDER BY clause..
35790 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73 74  **.** The [xBest
357a0 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d 75  Index] method mu
357b0 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72 61  st fill aConstra
357c0 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68 20  intUsage[] with 
357d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
357e0 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d 65  bout what parame
357f0 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f 20  ters to pass to 
35800 78 46 69 6c 74 65 72 2e 20 20 5e 49 66 20 61 72  xFilter.  ^If ar
35810 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a 2a  gvIndex>0 then.*
35820 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e 64  * the right-hand
35830 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f 72   side of the cor
35840 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e 73  responding aCons
35850 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61 6c  traint[] is eval
35860 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65 63  uated.** and bec
35870 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e 64  omes the argvInd
35880 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20 61  ex-th entry in a
35890 72 67 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e 73  rgv.  ^(If aCons
358a0 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f 6d  traintUsage[].om
358b0 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20 74  it.** is true, t
358c0 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61 69  hen the constrai
358d0 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74 6f  nt is assumed to
358e0 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c 65   be fully handle
358f0 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72 74  d by the.** virt
35900 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69 73  ual table and is
35910 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67 61   not checked aga
35920 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 29 5e 0a  in by SQLite.)^.
35930 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 78 4e 75  **.** ^The idxNu
35940 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61 6c  m and idxPtr val
35950 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65 64  ues are recorded
35960 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74 6f   and passed into
35970 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65 72   the.** [xFilter
35980 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b 73  ] method..** ^[s
35990 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
359a0 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20 69  s used to free i
359b0 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e 6c  dxPtr if and onl
359c0 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54 6f 46 72  y if.** needToFr
359d0 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75 65  eeIdxPtr is true
359e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72 64  ..**.** ^The ord
359f0 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65 61  erByConsumed mea
35a00 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20 66  ns that output f
35a10 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b 78  rom [xFilter]/[x
35a20 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75 72  Next] will occur
35a30 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72 65   in.** the corre
35a40 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74 69  ct order to sati
35a50 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42 59  sfy the ORDER BY
35a60 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74 20   clause so that 
35a70 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 73  no separate.** s
35a80 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20 72  orting step is r
35a90 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
35aa0 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  The estimatedCos
35ab0 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65 73  t value is an es
35ac0 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63 6f  timate of the co
35ad0 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65 0a  st of doing the.
35ae0 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c 6f  ** particular lo
35af0 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73 63  okup.  A full sc
35b00 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77 69  an of a table wi
35b10 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68 6f  th N entries sho
35b20 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63 6f  uld have.** a co
35b30 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e 61  st of N.  A bina
35b40 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20 74  ry search of a t
35b50 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69 65  able of N entrie
35b60 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61 0a  s should have a.
35b70 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72 6f  ** cost of appro
35b80 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29 2e  ximately log(N).
35b90 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
35ba0 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b 0a  e3_index_info {.
35bb0 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a 20    /* Inputs */. 
35bc0 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e 74   int nConstraint
35bd0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ;           /* N
35be0 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65 73  umber of entries
35bf0 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 20   in aConstraint 
35c00 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
35c10 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72  te3_index_constr
35c20 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74 20  aint {.     int 
35c30 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20  iColumn;        
35c40 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20        /* Column 
35c50 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  on left-hand sid
35c60 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74 20  e of constraint 
35c70 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65 64  */.     unsigned
35c80 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20 20   char op;       
35c90 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74 20    /* Constraint 
35ca0 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20 20  operator */.    
35cb0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 75   unsigned char u
35cc0 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54 72  sable;     /* Tr
35cd0 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73 74  ue if this const
35ce0 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65 20  raint is usable 
35cf0 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65 72  */.     int iTer
35d00 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20 20  mOffset;        
35d10 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72 6e    /* Used intern
35d20 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64 65  ally - xBestInde
35d30 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65 20  x should ignore 
35d40 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72 61  */.  } *aConstra
35d50 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 20  int;            
35d60 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45 52  /* Table of WHER
35d70 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
35d80 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 4f  ints */.  int nO
35d90 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20 20  rderBy;         
35da0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
35db0 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20 4f  f terms in the O
35dc0 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
35dd0 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
35de0 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62 79  e3_index_orderby
35df0 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f 6c   {.     int iCol
35e00 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  umn;            
35e10 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d 62    /* Column numb
35e20 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67  er */.     unsig
35e30 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20 20  ned char desc;  
35e40 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f 72       /* True for
35e50 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66 6f   DESC.  False fo
35e60 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a 61  r ASC. */.  } *a
35e70 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20  OrderBy;        
35e80 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f 52         /* The OR
35e90 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a 2f  DER BY clause */
35ea0 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a 2f  .  /* Outputs */
35eb0 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  .  struct sqlite
35ec0 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61 69  3_index_constrai
35ed0 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20 69  nt_usage {.    i
35ee0 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20 20  nt argvIndex;   
35ef0 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e 30          /* if >0
35f00 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20  , constraint is 
35f10 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f 20  part of argv to 
35f20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20 75  xFilter */.    u
35f30 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d 69  nsigned char omi
35f40 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e 6f  t;      /* Do no
35f50 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66 6f  t code a test fo
35f60 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69 6e  r this constrain
35f70 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  t */.  } *aConst
35f80 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69 6e  raintUsage;.  in
35f90 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20 20  t idxNum;       
35fa0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
35fb0 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e 74  er used to ident
35fc0 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a 2f  ify the index */
35fd0 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72 3b  .  char *idxStr;
35fe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
35ff0 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62 6c   String, possibl
36000 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
36010 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20 2a  sqlite3_malloc *
36020 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46 72  /.  int needToFr
36030 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20 2f  eeIdxStr;      /
36040 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75 73  * Free idxStr us
36050 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
36060 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20 20  () if true */.  
36070 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73 75  int orderByConsu
36080 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54 72  med;       /* Tr
36090 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73 20  ue if output is 
360a0 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64 20  already ordered 
360b0 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74 69  */.  double esti
360c0 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20 20  matedCost;      
360d0 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f 73  /* Estimated cos
360e0 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 20  t of using this 
360f0 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  index */.};../*.
36100 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
36110 74 75 61 6c 20 54 61 62 6c 65 20 43 6f 6e 73 74  tual Table Const
36120 72 61 69 6e 74 20 4f 70 65 72 61 74 6f 72 20 43  raint Operator C
36130 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
36140 20 6d 61 63 72 6f 73 20 64 65 66 69 6e 65 64 20   macros defined 
36150 74 68 65 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75  the allowed valu
36160 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 73  es for the.** [s
36170 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
36180 6f 5d 2e 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  o].aConstraint[]
36190 2e 6f 70 20 66 69 65 6c 64 2e 20 20 45 61 63 68  .op field.  Each
361a0 20 76 61 6c 75 65 20 72 65 70 72 65 73 65 6e 74   value represent
361b0 73 0a 2a 2a 20 61 6e 20 6f 70 65 72 61 74 6f 72  s.** an operator
361c0 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66   that is part of
361d0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 74 65   a constraint te
361e0 72 6d 20 69 6e 20 74 68 65 20 77 48 45 52 45 20  rm in the wHERE 
361f0 63 6c 61 75 73 65 20 6f 66 0a 2a 2a 20 61 20 71  clause of.** a q
36200 75 65 72 79 20 74 68 61 74 20 75 73 65 73 20 61  uery that uses a
36210 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
36220 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
36230 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
36240 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64 65  AINT_EQ    2.#de
36250 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
36260 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54 20  X_CONSTRAINT_GT 
36270 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
36280 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
36290 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64 65  AINT_LE    8.#de
362a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
362b0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54 20  X_CONSTRAINT_LT 
362c0 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
362d0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
362e0 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a 23  RAINT_GE    32.#
362f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
36300 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4d  DEX_CONSTRAINT_M
36310 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20 43  ATCH 64../*.** C
36320 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
36330 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62 6c  r A Virtual Tabl
36340 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e Implementation
36350 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
36360 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
36370 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e 65  to register a ne
36380 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  w [virtual table
36390 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a 2a   module] name..*
363a0 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73 20  * ^Module names 
363b0 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65 72  must be register
363c0 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72 65  ed before.** cre
363d0 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69 72  ating a new [vir
363e0 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69 6e  tual table] usin
363f0 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e 64  g the module and
36400 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61 0a   before using a.
36410 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20 5b  ** preexisting [
36420 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 66  virtual table] f
36430 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a  or the module..*
36440 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c 65  *.** ^The module
36450 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74 65   name is registe
36460 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  red on the [data
36470 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36480 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
36490 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
364a0 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d 65  eter.  ^The name
364b0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
364c0 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 0a  s given by the .
364d0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
364e0 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72 64  ter.  ^The third
364f0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
36500 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74 68  pointer to.** th
36510 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
36520 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c   of the [virtual
36530 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
36540 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a 2a    ^The fourth.**
36550 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
36560 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65 6e   arbitrary clien
36570 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  t data pointer t
36580 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74 68  hat is passed th
36590 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74 68  rough.** into th
365a0 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20  e [xCreate] and 
365b0 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f  [xConnect] metho
365c0 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75 61  ds of the virtua
365d0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a 2a  l table module.*
365e0 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69 72  * when a new vir
365f0 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62 65  tual table is be
36600 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20 6f   being created o
36610 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64 2e  r reinitialized.
36620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36630 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
36640 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
36650 20 68 61 73 20 61 20 66 69 66 74 68 20 70 61 72   has a fifth par
36660 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
36670 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
36680 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  a destructor for
36690 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74 61   the pClientData
366a0 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 0a  .  ^SQLite will.
366b0 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ** invoke the de
366c0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
366d0 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74 20  n (if it is not 
366e0 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69 74  NULL) when SQLit
366f0 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e  e.** no longer n
36700 65 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e 74  eeds the pClient
36710 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20 5e  Data pointer.  ^
36720 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 77  The destructor w
36730 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 69  ill also.** be i
36740 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61  nvoked if the ca
36750 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  ll to sqlite3_cr
36760 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
36770 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 54 68 65 20   fails..** ^The 
36780 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
36790 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65 72  odule().** inter
367a0 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c 65  face is equivale
367b0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  nt to sqlite3_cr
367c0 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29  eate_module_v2()
367d0 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a 20   with a NULL.** 
367e0 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a 69  destructor..*/.i
367f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
36800 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71 6c 69  e_module(.  sqli
36810 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
36820 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
36830 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
36840 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
36850 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
36860 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
36870 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
36880 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
36890 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
368a0 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74  ule *p,   /* Met
368b0 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
368c0 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  ule */.  void *p
368d0 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20 20 20  ClientData      
368e0 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
368f0 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
36900 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a 69 6e  Connect */.);.in
36910 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
36920 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71  _module_v2(.  sq
36930 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
36940 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
36950 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
36960 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
36970 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
36980 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
36990 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
369a0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
369b0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
369c0 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
369d0 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
369e0 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
369f0 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20  *pClientData,   
36a00 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
36a10 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
36a20 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76  /xConnect */.  v
36a30 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
36a40 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64  oid*)     /* Mod
36a50 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  ule destructor f
36a60 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f  unction */.);../
36a70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
36a80 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73  irtual Table Ins
36a90 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  tance Object.** 
36aa0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
36ab0 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65  3_vtab.**.** Eve
36ac0 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ry [virtual tabl
36ad0 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d  e module] implem
36ae0 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20  entation uses a 
36af0 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74  subclass.** of t
36b00 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20 64 65  his object to de
36b10 73 63 72 69 62 65 20 61 20 70 61 72 74 69 63 75  scribe a particu
36b20 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20  lar instance.** 
36b30 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
36b40 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75  table].  Each su
36b50 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62  bclass will.** b
36b60 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68  e tailored to th
36b70 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73  e specific needs
36b80 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69   of the module i
36b90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
36ba0 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66  * The purpose of
36bb0 20 74 68 69 73 20 73 75 70 65 72 63 6c 61 73 73   this superclass
36bc0 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65   is to define ce
36bd0 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61  rtain fields tha
36be0 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20  t are.** common 
36bf0 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d  to all module im
36c00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a  plementations..*
36c10 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74 61  *.** ^Virtual ta
36c20 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e  bles methods can
36c30 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65   set an error me
36c40 73 73 61 67 65 20 62 79 20 61 73 73 69 67 6e 69  ssage by assigni
36c50 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  ng a.** string o
36c60 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
36c70 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
36c80 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68   to zErrMsg.  Th
36c90 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a  e method should.
36ca0 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74 68 61  ** take care tha
36cb0 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69  t any prior stri
36cc0 6e 67 20 69 73 20 66 72 65 65 64 20 62 79 20 61  ng is freed by a
36cd0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
36ce0 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69  3_free()].** pri
36cf0 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20  or to assigning 
36d00 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20  a new string to 
36d10 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74 65 72  zErrMsg.  ^After
36d20 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
36d30 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72  ge.** is deliver
36d40 65 64 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69  ed up to the cli
36d50 65 6e 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ent application,
36d60 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
36d70 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   be automaticall
36d80 79 0a 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71  y.** freed by sq
36d90 6c 69 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64  lite3_free() and
36da0 20 74 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65   the zErrMsg fie
36db0 6c 64 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65  ld will be zeroe
36dc0 64 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  d..*/.struct sql
36dd0 69 74 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f  ite3_vtab {.  co
36de0 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  nst sqlite3_modu
36df0 6c 65 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a  le *pModule;  /*
36e00 20 54 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20   The module for 
36e10 74 68 69 73 20 76 69 72 74 75 61 6c 20 74 61 62  this virtual tab
36e20 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66  le */.  int nRef
36e30 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
36e40 20 20 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f          /* NO LO
36e50 4e 47 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63  NGER USED */.  c
36e60 68 61 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20  har *zErrMsg;   
36e70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
36e80 2a 20 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20  * Error message 
36e90 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72  from sqlite3_mpr
36ea0 69 6e 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56  intf() */.  /* V
36eb0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
36ec0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
36ed0 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
36ee0 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
36ef0 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
36f00 41 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c  API3REF: Virtual
36f10 20 54 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62   Table Cursor Ob
36f20 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
36f30 3a 20 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  : sqlite3_vtab_c
36f40 75 72 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74  ursor {virtual t
36f50 61 62 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a  able cursor}.**.
36f60 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75 61  ** Every [virtua
36f70 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20  l table module] 
36f80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75  implementation u
36f90 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ses a subclass o
36fa0 66 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  f the.** followi
36fb0 6e 67 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  ng structure to 
36fc0 64 65 73 63 72 69 62 65 20 63 75 72 73 6f 72 73  describe cursors
36fd0 20 74 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f   that point into
36fe0 20 74 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   the.** [virtual
36ff0 20 74 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20   table] and are 
37000 75 73 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20  used.** to loop 
37010 74 68 72 6f 75 67 68 20 74 68 65 20 76 69 72 74  through the virt
37020 75 61 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73  ual table.  Curs
37030 6f 72 73 20 61 72 65 20 63 72 65 61 74 65 64 20  ors are created 
37040 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
37050 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70  lite3_module.xOp
37060 65 6e 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68  en | xOpen] meth
37070 6f 64 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  od of the module
37080 20 61 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79   and are destroy
37090 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71  ed.** by the [sq
370a0 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c  lite3_module.xCl
370b0 6f 73 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65  ose | xClose] me
370c0 74 68 6f 64 2e 20 20 43 75 72 73 6f 72 73 20 61  thod.  Cursors a
370d0 72 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  re used.** by th
370e0 65 20 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e  e [xFilter], [xN
370f0 65 78 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78  ext], [xEof], [x
37100 43 6f 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52  Column], and [xR
37110 6f 77 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a  owid] methods.**
37120 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20   of the module. 
37130 20 45 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70   Each module imp
37140 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
37150 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63   define.** the c
37160 6f 6e 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73  ontent of a curs
37170 6f 72 20 73 74 72 75 63 74 75 72 65 20 74 6f 20  or structure to 
37180 73 75 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65  suit its own nee
37190 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  ds..**.** This s
371a0 75 70 65 72 63 6c 61 73 73 20 65 78 69 73 74 73  uperclass exists
371b0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66   in order to def
371c0 69 6e 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68  ine fields of th
371d0 65 20 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a  e cursor that.**
371e0 20 61 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61   are common to a
371f0 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ll implementatio
37200 6e 73 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71  ns..*/.struct sq
37210 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
37220 72 20 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74  r {.  sqlite3_vt
37230 61 62 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20  ab *pVtab;      
37240 2f 2a 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65  /* Virtual table
37250 20 6f 66 20 74 68 69 73 20 63 75 72 73 6f 72 20   of this cursor 
37260 2a 2f 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20  */.  /* Virtual 
37270 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  table implementa
37280 74 69 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63  tions will typic
37290 61 6c 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f  ally add additio
372a0 6e 61 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b  nal fields */.};
372b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
372c0 3a 20 44 65 63 6c 61 72 65 20 54 68 65 20 53 63  : Declare The Sc
372d0 68 65 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61  hema Of A Virtua
372e0 6c 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54  l Table.**.** ^T
372f0 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64  he [xCreate] and
37300 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68   [xConnect] meth
37310 6f 64 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72  ods of a.** [vir
37320 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c  tual table modul
37330 65 5d 20 63 61 6c 6c 20 74 68 69 73 20 69 6e 74  e] call this int
37340 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63  erface.** to dec
37350 6c 61 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20  lare the format 
37360 28 74 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64  (the names and d
37370 61 74 61 74 79 70 65 73 20 6f 66 20 74 68 65 20  atatypes of the 
37380 63 6f 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74  columns) of.** t
37390 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
373a0 73 20 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74  s they implement
373b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
373c0 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28 73 71  _declare_vtab(sq
373d0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
373e0 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a 0a 2a  ar *zSQL);../*.*
373f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76 65 72  * CAPI3REF: Over
37400 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f 6e 20  load A Function 
37410 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  For A Virtual Ta
37420 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69 72 74  ble.**.** ^(Virt
37430 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e 20 70  ual tables can p
37440 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61 74 69  rovide alternati
37450 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ve implementatio
37460 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ns of functions.
37470 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 78 46  ** using the [xF
37480 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d 65 74  indFunction] met
37490 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69 72 74  hod of the [virt
374a0 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
374b0 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c 6f 62  ].  .** But glob
374c0 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 74  al versions of t
374d0 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  hose functions.*
374e0 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69 6e 20  * must exist in 
374f0 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76 65 72  order to be over
37500 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  loaded.)^.**.** 
37510 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b 65 73  ^(This API makes
37520 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c 20 76   sure a global v
37530 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75 6e 63  ersion of a func
37540 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61 72 74  tion with a part
37550 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65 20 61  icular.** name a
37560 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 72  nd number of par
37570 61 6d 65 74 65 72 73 20 65 78 69 73 74 73 2e 20  ameters exists. 
37580 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75 6e 63   If no such func
37590 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a 20 62  tion exists.** b
375a0 65 66 6f 72 65 20 74 68 69 73 20 41 50 49 20 69  efore this API i
375b0 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65 77 20  s called, a new 
375c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72 65 61  function is crea
375d0 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69 6d 70  ted.)^  ^The imp
375e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 6f  lementation.** o
375f0 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74 69  f the new functi
37600 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73 65 73  on always causes
37610 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20 74 6f   an exception to
37620 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53 6f 0a   be thrown.  So.
37630 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e 63 74  ** the new funct
37640 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f 64 20  ion is not good 
37650 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62 79 20  for anything by 
37660 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f 6e 6c  itself.  Its onl
37670 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69 73 20  y.** purpose is 
37680 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68 6f 6c  to be a placehol
37690 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  der function tha
376a0 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c 6f 61  t can be overloa
376b0 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76 69 72  ded.** by a [vir
376c0 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a  tual table]..*/.
376d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 76 65 72  int sqlite3_over
376e0 6c 6f 61 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71  load_function(sq
376f0 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68  lite3*, const ch
37700 61 72 20 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69  ar *zFuncName, i
37710 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a  nt nArg);../*.**
37720 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   The interface t
37730 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74 61  o the virtual-ta
37740 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 64 65  ble mechanism de
37750 66 69 6e 65 64 20 61 62 6f 76 65 20 28 62 61 63  fined above (bac
37760 6b 20 75 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d  k up.** to a com
37770 6d 65 6e 74 20 72 65 6d 61 72 6b 61 62 6c 79 20  ment remarkably 
37780 73 69 6d 69 6c 61 72 20 74 6f 20 74 68 69 73 20  similar to this 
37790 6f 6e 65 29 20 69 73 20 63 75 72 72 65 6e 74 6c  one) is currentl
377a0 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20  y considered.** 
377b0 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74  to be experiment
377c0 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  al.  The interfa
377d0 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  ce might change 
377e0 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20  in incompatible 
377f0 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ways..** If this
37800 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f   is a problem fo
37810 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73  r you, do not us
37820 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  e the interface 
37830 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a  at this time..**
37840 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72  .** When the vir
37850 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61  tual-table mecha
37860 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c  nism stabilizes,
37870 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65   we will declare
37880 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63   the.** interfac
37890 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74  e fixed, support
378a0 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79   it indefinitely
378b0 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69  , and remove thi
378c0 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f  s comment..*/../
378d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
378e0 20 48 61 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70   Handle To An Op
378f0 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f  en BLOB.** KEYWO
37900 52 44 53 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c  RDS: {BLOB handl
37910 65 7d 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  e} {BLOB handles
37920 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  }.**.** An insta
37930 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
37940 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
37950 20 6f 70 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68   open BLOB on wh
37960 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ich.** [sqlite3_
37970 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
37980 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
37990 5d 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  ] can be perform
379a0 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20  ed..** ^Objects 
379b0 6f 66 20 74 68 69 73 20 74 79 70 65 20 61 72 65  of this type are
379c0 20 63 72 65 61 74 65 64 20 62 79 20 5b 73 71 6c   created by [sql
379d0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29  ite3_blob_open()
379e0 5d 0a 2a 2a 20 61 6e 64 20 64 65 73 74 72 6f 79  ].** and destroy
379f0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 62  ed by [sqlite3_b
37a00 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  lob_close()]..**
37a10 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
37a20 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61 6e 64 20  lob_read()] and 
37a30 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
37a40 69 74 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ite()] interface
37a50 73 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  s.** can be used
37a60 20 74 6f 20 72 65 61 64 20 6f 72 20 77 72 69 74   to read or writ
37a70 65 20 73 6d 61 6c 6c 20 73 75 62 73 65 63 74 69  e small subsecti
37a80 6f 6e 73 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e  ons of the BLOB.
37a90 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
37aa0 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20  3_blob_bytes()] 
37ab0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
37ac0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
37ad0 65 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e  e BLOB in bytes.
37ae0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
37af0 63 74 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20  ct sqlite3_blob 
37b00 73 71 6c 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f  sqlite3_blob;../
37b10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
37b20 70 65 6e 20 41 20 42 4c 4f 42 20 46 6f 72 20 49  pen A BLOB For I
37b30 6e 63 72 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a  ncremental I/O.*
37b40 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
37b50 72 66 61 63 65 73 20 6f 70 65 6e 73 20 61 20 5b  rfaces opens a [
37b60 42 4c 4f 42 20 68 61 6e 64 6c 65 20 7c 20 68 61  BLOB handle | ha
37b70 6e 64 6c 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f  ndle] to the BLO
37b80 42 20 6c 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20  B located.** in 
37b90 72 6f 77 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e  row iRow, column
37ba0 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20   zColumn, table 
37bb0 7a 54 61 62 6c 65 20 69 6e 20 64 61 74 61 62 61  zTable in databa
37bc0 73 65 20 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74  se zDb;.** in ot
37bd0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73  her words, the s
37be0 61 6d 65 20 42 4c 4f 42 20 74 68 61 74 20 77 6f  ame BLOB that wo
37bf0 75 6c 64 20 62 65 20 73 65 6c 65 63 74 65 64 20  uld be selected 
37c00 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a  by:.**.** <pre>.
37c10 2a 2a 20 20 20 20 20 53 45 4c 45 43 54 20 7a 43  **     SELECT zC
37c20 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a  olumn FROM zDb.z
37c30 54 61 62 6c 65 20 57 48 45 52 45 20 5b 72 6f 77  Table WHERE [row
37c40 69 64 5d 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c  id] = iRow;.** <
37c50 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  /pre>)^.**.** ^I
37c60 66 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  f the flags para
37c70 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72  meter is non-zer
37c80 6f 2c 20 74 68 65 6e 20 74 68 65 20 42 4c 4f 42  o, then the BLOB
37c90 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
37ca0 65 61 64 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65  ead.** and write
37cb0 20 61 63 63 65 73 73 2e 20 5e 49 66 20 69 74 20   access. ^If it 
37cc0 69 73 20 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f  is zero, the BLO
37cd0 42 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  B is opened for 
37ce0 72 65 61 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20  read access..** 
37cf0 5e 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69  ^It is not possi
37d00 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f  ble to open a co
37d10 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72  lumn that is par
37d20 74 20 6f 66 20 61 6e 20 69 6e 64 65 78 20 6f 72  t of an index or
37d30 20 70 72 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79   primary .** key
37d40 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 20 5e 49   for writing. ^I
37d50 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  f [foreign key c
37d60 6f 6e 73 74 72 61 69 6e 74 73 5d 20 61 72 65 20  onstraints] are 
37d70 65 6e 61 62 6c 65 64 2c 20 69 74 20 69 73 20 0a  enabled, it is .
37d80 2a 2a 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  ** not possible 
37d90 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e  to open a column
37da0 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f 66   that is part of
37db0 20 61 20 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66   a [child key] f
37dc0 6f 72 20 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a  or writing..**.*
37dd0 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
37de0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 20 69   database name i
37df0 73 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 6e 61  s not the filena
37e00 6d 65 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73  me that contains
37e10 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
37e20 20 62 75 74 20 72 61 74 68 65 72 20 74 68 65 20   but rather the 
37e30 73 79 6d 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66  symbolic name of
37e40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 68   the database th
37e50 61 74 0a 2a 2a 20 61 70 70 65 61 72 73 20 61 66  at.** appears af
37e60 74 65 72 20 74 68 65 20 41 53 20 6b 65 79 77 6f  ter the AS keywo
37e70 72 64 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  rd when the data
37e80 62 61 73 65 20 69 73 20 63 6f 6e 6e 65 63 74 65  base is connecte
37e90 64 20 75 73 69 6e 67 20 5b 41 54 54 41 43 48 5d  d using [ATTACH]
37ea0 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61  ..** ^For the ma
37eb0 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
37ec0 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  , the database n
37ed0 61 6d 65 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a  ame is "main"..*
37ee0 2a 20 5e 46 6f 72 20 54 45 4d 50 20 74 61 62 6c  * ^For TEMP tabl
37ef0 65 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  es, the database
37f00 20 6e 61 6d 65 20 69 73 20 22 74 65 6d 70 22 2e   name is "temp".
37f10 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63  .**.** ^(On succ
37f20 65 73 73 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ess, [SQLITE_OK]
37f30 20 69 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64   is returned and
37f40 20 74 68 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68   the new [BLOB h
37f50 61 6e 64 6c 65 5d 20 69 73 20 77 72 69 74 74 65  andle] is writte
37f60 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e  n.** to *ppBlob.
37f70 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
37f80 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
37f90 74 75 72 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c  turned and *ppBl
37fa0 6f 62 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  ob is set.** to 
37fb0 62 65 20 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65  be a null pointe
37fc0 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75  r.)^.** ^This fu
37fd0 6e 63 74 69 6f 6e 20 73 65 74 73 20 74 68 65 20  nction sets the 
37fe0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37ff0 74 69 6f 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65  tion] error code
38000 20 61 6e 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20   and message.** 
38010 61 63 63 65 73 73 69 62 6c 65 20 76 69 61 20 5b  accessible via [
38020 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
38030 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
38040 65 72 72 6d 73 67 28 29 5d 20 61 6e 64 20 72 65  errmsg()] and re
38050 6c 61 74 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f  lated.** functio
38060 6e 73 2e 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  ns. ^Note that t
38070 68 65 20 2a 70 70 42 6c 6f 62 20 76 61 72 69 61  he *ppBlob varia
38080 62 6c 65 20 69 73 20 61 6c 77 61 79 73 20 69 6e  ble is always in
38090 69 74 69 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a  itialized in a.*
380a0 2a 20 77 61 79 20 74 68 61 74 20 6d 61 6b 65 73  * way that makes
380b0 20 69 74 20 73 61 66 65 20 74 6f 20 69 6e 76 6f   it safe to invo
380c0 6b 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ke [sqlite3_blob
380d0 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70  _close()] on *pp
380e0 42 6c 6f 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65  Blob.** regardle
380f0 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
38100 73 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  s or failure of 
38110 74 68 69 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  this routine..**
38120 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 72 6f 77  .** ^(If the row
38130 20 74 68 61 74 20 61 20 42 4c 4f 42 20 68 61 6e   that a BLOB han
38140 64 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  dle points to is
38150 20 6d 6f 64 69 66 69 65 64 20 62 79 20 61 6e 0a   modified by an.
38160 2a 2a 20 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45  ** [UPDATE], [DE
38170 4c 45 54 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e  LETE], or by [ON
38180 20 43 4f 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d   CONFLICT] side-
38190 65 66 66 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20  effects.** then 
381a0 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20  the BLOB handle 
381b0 69 73 20 6d 61 72 6b 65 64 20 61 73 20 22 65 78  is marked as "ex
381c0 70 69 72 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20  pired"..** This 
381d0 69 73 20 74 72 75 65 20 69 66 20 61 6e 79 20 63  is true if any c
381e0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77  olumn of the row
381f0 20 69 73 20 63 68 61 6e 67 65 64 2c 20 65 76 65   is changed, eve
38200 6e 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74  n a column.** ot
38210 68 65 72 20 74 68 61 6e 20 74 68 65 20 6f 6e 65  her than the one
38220 20 74 68 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65   the BLOB handle
38230 20 69 73 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a   is open on.)^.*
38240 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  * ^Calls to [sql
38250 69 74 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29  ite3_blob_read()
38260 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
38270 6c 6f 62 5f 77 72 69 74 65 28 29 5d 20 66 6f 72  lob_write()] for
38280 0a 2a 2a 20 61 20 65 78 70 69 72 65 64 20 42 4c  .** a expired BL
38290 4f 42 20 68 61 6e 64 6c 65 20 66 61 69 6c 20 77  OB handle fail w
382a0 69 74 68 20 61 6e 20 72 65 74 75 72 6e 20 63 6f  ith an return co
382b0 64 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42  de of [SQLITE_AB
382c0 4f 52 54 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67  ORT]..** ^(Chang
382d0 65 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  es written into 
382e0 61 20 42 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20  a BLOB prior to 
382f0 74 68 65 20 42 4c 4f 42 20 65 78 70 69 72 69 6e  the BLOB expirin
38300 67 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c  g are not.** rol
38310 6c 65 64 20 62 61 63 6b 20 62 79 20 74 68 65 20  led back by the 
38320 65 78 70 69 72 61 74 69 6f 6e 20 6f 66 20 74 68  expiration of th
38330 65 20 42 4c 4f 42 2e 20 20 53 75 63 68 20 63 68  e BLOB.  Such ch
38340 61 6e 67 65 73 20 77 69 6c 6c 20 65 76 65 6e 74  anges will event
38350 75 61 6c 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20  ually.** commit 
38360 69 66 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  if the transacti
38370 6f 6e 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  on continues to 
38380 63 6f 6d 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a  completion.)^.**
38390 0a 2a 2a 20 5e 55 73 65 20 74 68 65 20 5b 73 71  .** ^Use the [sq
383a0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
383b0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
383c0 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 73   determine the s
383d0 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  ize of.** the op
383e0 65 6e 65 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65  ened blob.  ^The
383f0 20 73 69 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20   size of a blob 
38400 6d 61 79 20 6e 6f 74 20 62 65 20 63 68 61 6e 67  may not be chang
38410 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e  ed by this.** in
38420 74 65 72 66 61 63 65 2e 20 20 55 73 65 20 74 68  terface.  Use th
38430 65 20 5b 55 50 44 41 54 45 5d 20 53 51 4c 20 63  e [UPDATE] SQL c
38440 6f 6d 6d 61 6e 64 20 74 6f 20 63 68 61 6e 67 65  ommand to change
38450 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a   the size of a.*
38460 2a 20 62 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54  * blob..**.** ^T
38470 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
38480 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64  _zeroblob()] and
38490 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
384a0 5f 7a 65 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74  _zeroblob()] int
384b0 65 72 66 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74  erfaces.** and t
384c0 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72  he built-in [zer
384d0 6f 62 6c 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74  oblob] SQL funct
384e0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 2c  ion can be used,
384f0 20 69 66 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20   if desired,.** 
38500 74 6f 20 63 72 65 61 74 65 20 61 6e 20 65 6d 70  to create an emp
38510 74 79 2c 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20  ty, zero-filled 
38520 62 6c 6f 62 20 69 6e 20 77 68 69 63 68 20 74 6f  blob in which to
38530 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 75   read or write u
38540 73 69 6e 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74  sing.** this int
38550 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f  erface..**.** To
38560 20 61 76 6f 69 64 20 61 20 72 65 73 6f 75 72 63   avoid a resourc
38570 65 20 6c 65 61 6b 2c 20 65 76 65 72 79 20 6f 70  e leak, every op
38580 65 6e 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d  en [BLOB handle]
38590 20 73 68 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c   should eventual
385a0 6c 79 0a 2a 2a 20 62 65 20 72 65 6c 65 61 73 65  ly.** be release
385b0 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b  d by a call to [
385c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
385d0 73 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  se()]..*/.int sq
385e0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28  lite3_blob_open(
385f0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 63  .  sqlite3*,.  c
38600 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 2c 0a  onst char *zDb,.
38610 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 54    const char *zT
38620 61 62 6c 65 2c 0a 20 20 63 6f 6e 73 74 20 63 68  able,.  const ch
38630 61 72 20 2a 7a 43 6f 6c 75 6d 6e 2c 0a 20 20 73  ar *zColumn,.  s
38640 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 52 6f  qlite3_int64 iRo
38650 77 2c 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 0a  w,.  int flags,.
38660 20 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 2a    sqlite3_blob *
38670 2a 70 70 42 6c 6f 62 0a 29 3b 0a 0a 2f 2a 0a 2a  *ppBlob.);../*.*
38680 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 6f 76 65  * CAPI3REF: Move
38690 20 61 20 42 4c 4f 42 20 48 61 6e 64 6c 65 20 74   a BLOB Handle t
386a0 6f 20 61 20 4e 65 77 20 52 6f 77 0a 2a 2a 0a 2a  o a New Row.**.*
386b0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
386c0 20 69 73 20 75 73 65 64 20 74 6f 20 6d 6f 76 65   is used to move
386d0 20 61 6e 20 65 78 69 73 74 69 6e 67 20 62 6c 6f   an existing blo
386e0 62 20 68 61 6e 64 6c 65 20 73 6f 20 74 68 61 74  b handle so that
386f0 20 69 74 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f   it points.** to
38700 20 61 20 64 69 66 66 65 72 65 6e 74 20 72 6f 77   a different row
38710 20 6f 66 20 74 68 65 20 73 61 6d 65 20 64 61 74   of the same dat
38720 61 62 61 73 65 20 74 61 62 6c 65 2e 20 5e 54 68  abase table. ^Th
38730 65 20 6e 65 77 20 72 6f 77 20 69 73 20 69 64 65  e new row is ide
38740 6e 74 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ntified.** by th
38750 65 20 72 6f 77 69 64 20 76 61 6c 75 65 20 70 61  e rowid value pa
38760 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
38770 6e 64 20 61 72 67 75 6d 65 6e 74 2e 20 4f 6e 6c  nd argument. Onl
38780 79 20 74 68 65 20 72 6f 77 20 63 61 6e 20 62 65  y the row can be
38790 0a 2a 2a 20 63 68 61 6e 67 65 64 2e 20 5e 54 68  .** changed. ^Th
387a0 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
387b0 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6f 6e 20  e and column on 
387c0 77 68 69 63 68 20 74 68 65 20 62 6c 6f 62 20 68  which the blob h
387d0 61 6e 64 6c 65 20 69 73 20 6f 70 65 6e 0a 2a 2a  andle is open.**
387e0 20 72 65 6d 61 69 6e 20 74 68 65 20 73 61 6d 65   remain the same
387f0 2e 20 4d 6f 76 69 6e 67 20 61 6e 20 65 78 69 73  . Moving an exis
38800 74 69 6e 67 20 62 6c 6f 62 20 68 61 6e 64 6c 65  ting blob handle
38810 20 74 6f 20 61 20 6e 65 77 20 72 6f 77 20 63 61   to a new row ca
38820 6e 20 62 65 0a 2a 2a 20 66 61 73 74 65 72 20 74  n be.** faster t
38830 68 61 6e 20 63 6c 6f 73 69 6e 67 20 74 68 65 20  han closing the 
38840 65 78 69 73 74 69 6e 67 20 68 61 6e 64 6c 65 20  existing handle 
38850 61 6e 64 20 6f 70 65 6e 69 6e 67 20 61 20 6e 65  and opening a ne
38860 77 20 6f 6e 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  w one..**.** ^(T
38870 68 65 20 6e 65 77 20 72 6f 77 20 6d 75 73 74 20  he new row must 
38880 6d 65 65 74 20 74 68 65 20 73 61 6d 65 20 63 72  meet the same cr
38890 69 74 65 72 69 61 20 61 73 20 66 6f 72 20 5b 73  iteria as for [s
388a0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
388b0 28 29 5d 20 2d 0a 2a 2a 20 69 74 20 6d 75 73 74  ()] -.** it must
388c0 20 65 78 69 73 74 20 61 6e 64 20 74 68 65 72 65   exist and there
388d0 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
388e0 61 20 62 6c 6f 62 20 6f 72 20 74 65 78 74 20 76  a blob or text